oauth2
Module oauth2
ballerina/oauth2
Package Overview
This package provides a listener OAuth2 authentication provider, which can be used to authenticate the provided credentials against an introspection endpoint, and a client OAuth2 authentication provider, which can be used to authenticate against an external endpoint.
For information on the operations, which you can perform with this package, see the below Functions. For examples on the usage of the operations, see the following.
Classes
oauth2: ClientOAuth2Provider
Represents the client OAuth2 provider, which generates OAuth2 tokens. This supports the client credentials grant type, password grant type, and the refresh token grant type.
- Client Credentials Grant Type
oauth2:ClientOAuth2Provider provider = new({ tokenUrl: "https://localhost:9196/oauth2/token", clientId: "3MVG9YDQS5WtC11paU2WcQjBB3L", clientSecret: "9205371918321623741", scopes: ["token-scope1", "token-scope2"] });
- Password Grant Type
oauth2:ClientOAuth2Provider provider = new({ tokenUrl: "https://localhost:9196/oauth2/token/authorize/header", username: "johndoe", password: "A3ddj3w", clientId: "3MVG9YDQS5WtC11paU2WcQjBB3L", clientSecret: "9205371918321623741", scopes: ["token-scope1", "token-scope2"] });
- Refresh Token Grant Type
oauth2:ClientOAuth2Provider provider = new({ refreshUrl: "https://localhost:9196/oauth2/token/refresh", refreshToken: "XlfBs91yquexJqDaKEMzVg==", clientId: "3MVG9YDQS5WtC11paU2WcQjBB3L", clientSecret: "9205371918321623741", scopes: ["token-scope1", "token-scope2"] });
Constructor
Provides authentication based on the provided OAuth2 configurations.
init (GrantConfig grantConfig)
- grantConfig GrantConfig - OAuth2 grant type configurations
generateToken
Get an OAuth2 access token from authorization server for the OAuth2 authentication.
string:oauth2:Error token = provider.generateToken();
oauth2: ListenerOAuth2Provider
Represents the inbound OAuth2 provider, which calls the introspection server, validates the received credentials, and performs authentication and authorization.
oauth2:IntrospectionConfig config = { url: "https://localhost:9196/oauth2/token/introspect" }; oauth2:ListenerOAuth2Provider provider = new(config);
Constructor
Provides authentication based on the provided introspection configurations.
init (IntrospectionConfig introspectionConfig)
- introspectionConfig IntrospectionConfig - OAuth2 introspection server configurations
authorize
function authorize(string credential, map<string>? optionalParams) returns IntrospectionResponse|Error
Authenticates the provider OAuth2 tokens against the introspection endpoint.
boolean|oauth2:Error result = provider.authenticate("<credential>");
Parameters
- credential string - OAuth2 token to be authenticated
Return Type
- IntrospectionResponse|Error -
oauth2:IntrospectionResponse
if authentication is successful, or else anoauth2:Error
if an error occurred
Records
oauth2: CertKey
Represents combination of certificate, private key and private key password if encrypted.
Fields
- certFile string - A file containing the certificate
- keyFile string - A file containing the private key
- keyPassword string? - Password of the private key (if encrypted)
oauth2: ClientConfiguration
Represents the configurations of the client used to call the introspection endpoint.
Fields
- httpVersion HttpVersion(default HTTP_1_1) - The HTTP version of the client
- customPayload string? - The list of custom HTTP payload parameters
- auth ClientAuth? - The client auth configurations
- secureSocket SecureSocket? - SSL/TLS-related configurations
oauth2: ClientCredentialsGrantConfig
The data structure, which is used to configure the OAuth2 client credentials grant type.
Fields
- tokenUrl string - Token URL for the authorization endpoint
- clientId string - Client ID for the client credentials grant authentication
- clientSecret string - Client secret for the client credentials grant authentication
- scopes string[]? - Scope(s) of the access request
- defaultTokenExpTime decimal(default 3600) - Expiration time (in seconds) of the tokens if the authorization server response does not contain an
expires_in
field
- clockSkew decimal(default 0) - Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems
- credentialBearer CredentialBearer(default AUTH_HEADER_BEARER) - Bearer of the authentication credentials, which is sent to the authorization endpoint
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which are used to call the authorization endpoint
oauth2: IntrospectionConfig
Represents the introspection server configurations.
Fields
- url string - URL of the introspection server
- tokenTypeHint string? - A hint about the type of the token submitted for introspection
- cacheConfig CacheConfig? - Configurations for the cache used to store the OAuth2 token and other related information
- defaultTokenExpTime decimal(default 3600) - Expiration time (in seconds) of the tokens if the introspection response does not contain an
exp
field
- clientConfig ClientConfiguration(default {}) - HTTP client configurations which calls the introspection server
oauth2: IntrospectionResponse
Represents the introspection server response.
Fields
- active boolean - Boolean indicator of whether or not the presented token is currently active
- scope string? - A JSON string containing a space-separated list of scopes associated with this token
- clientId string? - Client identifier for the OAuth 2.0 client, which requested this token
- username string? - Resource owner who authorized this token
- tokenType string? - Type of the token
- exp int? - Expiry time (seconds since the Epoch)
- iat int? - Time when the token was issued originally (seconds since the Epoch)
- nbf int? - Token is not to be used before this time (seconds since the Epoch)
- sub string? - Subject of the token
- aud string? - Intended audience of the token
- iss string? - Issuer of the token
- jti string? - String identifier for the token
oauth2: PasswordGrantConfig
The data structure, which is used to configure the OAuth2 password grant type.
Fields
- tokenUrl string - Token URL for the authorization endpoint
- username string - Username for the password grant authentication
- password string - Password for the password grant authentication
- clientId string? - Client ID for the password grant authentication
- clientSecret string? - Client secret for the password grant authentication
- scopes string[]? - Scope(s) of the access request
- refreshConfig record {| string refreshUrl; string[] scopes?; map<string> optionalParams?; CredentialBearer credentialBearer = AUTH_HEADER_BEARER; ClientConfiguration clientConfig = {}; |} ? - Configurations for refreshing the access token
- defaultTokenExpTime decimal(default 3600) - Expiration time (in seconds) of the tokens if the authorization server response does not contain an
expires_in
field
- clockSkew decimal(default 0) - Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems
- credentialBearer CredentialBearer(default AUTH_HEADER_BEARER) - Bearer of the authentication credentials, which is sent to the authorization endpoint
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which are used to call the authorization endpoint
oauth2: RefreshTokenGrantConfig
The data structure, which can be used to configure OAuth2 refresh token grant type.
Fields
- refreshUrl string - Refresh token URL for the refresh token server
- refreshToken string - Refresh token for the refresh token server
- clientId string - Client ID for authentication with the authorization endpoint
- clientSecret string - Client secret for authentication with the authorization endpoint
- scopes string[]? - Scope(s) of the access request
- defaultTokenExpTime decimal(default 3600) - Expiration time (in seconds) of the tokens if the authorization server response does not contain an
expires_in
field
- clockSkew decimal(default 0) - Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems
- credentialBearer CredentialBearer(default AUTH_HEADER_BEARER) - Bearer of the authentication credentials, which is sent to the authorization endpoint
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which are used to call the authorization endpoint
oauth2: SecureSocket
Represents the SSL/TLS configurations.
Fields
- disable boolean(default false) - Disable SSL validation
- cert TrustStore|string - Configurations associated with the
crypto:TrustStore
or single certificate file that the client trusts
Enums
oauth2: CredentialBearer
Represents HTTP versions.
Members
oauth2: HttpVersion
Represents HTTP versions.
Members
Types
oauth2: ClientAuth
Defines the authentication configuration types for the HTTP client used for token introspection.
oauth2: GrantConfig
Represents the grant type configurations supported for OAuth2.
Errors
oauth2: Error
Represents the OAuth2 error. This will be returned if an error occurred while listener OAuth2 provider try to authenticate the received credentials and client OAuth 2provider try to generate the token.