Module oauth2
ballerina/oauth2 Ballerina library
Overview
This module provides a framework for interacting with OAuth2 authorization servers as specified in the RFC 6749 and RFC 7662.
The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service or by allowing the third-party application to obtain access on its own behalf.
The Ballerina oauth2 module facilitates auth providers that are to be used by the clients and listeners of different protocol connectors.
Listener OAuth2 Provider
Represents the listener OAuth2 provider, which is used to validate the received credential (access token) by calling the configured OAuth2 introspection endpoint.
Client OAuth2 Provider
Represents the client OAuth2 provider, which is used to generate OAuth2 access tokens using the configured OAuth2 token endpoint configurations. This supports the client credentials grant type, password grant type, and refresh token grant type.
Classes
oauth2: ClientOAuth2Provider
Represents the client OAuth2 provider, which is used to generate OAuth2 access tokens using the configured OAuth2 token endpoint configurations. This supports the client credentials grant type, password grant type, refresh token grant type, and the JWT bearer grant type.
- Client Credentials Grant Type
oauth2:ClientOAuth2Provider provider = new({ tokenUrl: "https://localhost:9445/oauth2/token", clientId: "3MVG9YDQS5WtC11paU2WcQjBB3L", clientSecret: "9205371918321623741", scopes: ["token-scope1", "token-scope2"] });
- Password Grant Type
oauth2:ClientOAuth2Provider provider = new({ tokenUrl: "https://localhost:9445/oauth2/token", username: "johndoe", password: "A3ddj3w", clientId: "3MVG9YDQS5WtC11paU2WcQjBB3L", clientSecret: "9205371918321623741", scopes: ["token-scope1", "token-scope2"] });
- Refresh Token Grant Type
oauth2:ClientOAuth2Provider provider = new({ refreshUrl: "https://localhost:9445/oauth2/token", refreshToken: "XlfBs91yquexJqDaKEMzVg==", clientId: "3MVG9YDQS5WtC11paU2WcQjBB3L", clientSecret: "9205371918321623741", scopes: ["token-scope1", "token-scope2"] });
Constructor
Provides authorization based on the provided OAuth2 configurations.
init (GrantConfig grantConfig)- grantConfig GrantConfig - OAuth2 grant type configurations
generateToken
Get an OAuth2 access token from the token endpoint.
string token = check provider.generateToken();
oauth2: ListenerOAuth2Provider
Represents the listener OAuth2 provider, which is used to validate the received credential (access token) by calling the configured introspection endpoint.
oauth2:IntrospectionConfig config = { url: "https://localhost:9196/oauth2/token/introspect" }; oauth2:ListenerOAuth2Provider provider = new(config);
Constructor
Provides authorization based on the provided introspection configurations.
init (IntrospectionConfig introspectionConfig)- introspectionConfig IntrospectionConfig - Introspection endpoint configurations
authorize
function authorize(string credential, map<string>? optionalParams) returns IntrospectionResponse|ErrorValidates the provided OAuth2 acess token against the introspection endpoint.
boolean result = check provider.authorize("<credential>");
Parameters
- credential string - OAuth2 access token to be validated
Return Type
- IntrospectionResponse|Error - An
oauth2:IntrospectionResponseif the validation is successful or else anoauth2:Errorif an error occurred
Enums
oauth2: CredentialBearer
Represents the credential-bearing methods.
Members
oauth2: HttpVersion
Represents the HTTP versions.
Members
Records
oauth2: CertKey
Represents the combination of the certificate file path, private key file path, 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
Represents the data structure, which is used to configure the OAuth2 client credentials grant type.
Fields
- tokenUrl string - Token URL of the token endpoint
- clientId string - Client ID of the client authentication
- clientSecret string - Client secret of the client authentication
- scopes string[]? - Scope(s) of the access request
- defaultTokenExpTime decimal(default 3600) - Expiration time (in seconds) of the tokens if the token endpoint response does not contain an
expires_infield
- 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 token endpoint
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which are used to call the token endpoint
oauth2: IntrospectionConfig
Represents the introspection endpoint configurations.
Fields
- url string - URL of the introspection endpoint
- tokenTypeHint string? - A hint about the type of the token submitted for introspection
- cacheConfig CacheConfig? - Configurations for the cache used to store the OAuth2 access token and other related information
- defaultTokenExpTime decimal(default 3600) - Expiration time (in seconds) of the tokens if the introspection response does not contain an
expfield
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which call the introspection endpoint
oauth2: IntrospectionResponse
Represents the introspection endpoint 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: JwtBearerGrantConfig
Represents the data structure, which is used to configure the OAuth2 JWT bearer grant type.
Fields
- tokenUrl string - Token URL of the token endpoint
- assertion string - A single JWT for the JWT bearer grant type
- clientId string? - Client ID of the client authentication
- clientSecret string? - Client secret of the client authentication
- scopes string[]? - Scope(s) of the access request
- defaultTokenExpTime decimal(default 3600) - Expiration time (in seconds) of the tokens if the token endpoint response does not contain an
expires_infield
- 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 token endpoint
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which are used to call the token endpoint
oauth2: PasswordGrantConfig
Represents the data structure, which is used to configure the OAuth2 password grant type.
Fields
- tokenUrl string - Token URL of the token endpoint
- username string - Username for the password grant type
- password string - Password for the password grant type
- clientId string? - Client ID of the client authentication
- clientSecret string? - Client secret of the client authentication
- scopes string[]? - Scope(s) of the access request
- refreshConfig record {| refreshUrl string, scopes string[], optionalParams map<string>, credentialBearer CredentialBearer, clientConfig ClientConfiguration |}? - Configurations for refreshing the access token
- defaultTokenExpTime decimal(default 3600) - Expiration time (in seconds) of the tokens if the token endpoint response does not contain an
expires_infield
- 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 token endpoint
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which are used to call the token endpoint
oauth2: RefreshTokenGrantConfig
Represents the data structure, which is used to configure the OAuth2 refresh token grant type.
Fields
- refreshUrl string - Refresh token URL of the token endpoint
- refreshToken string - Refresh token for the token endpoint
- clientId string - Client ID of the client authentication
- clientSecret string - Client secret of the client authentication
- scopes string[]? - Scope(s) of the access request
- defaultTokenExpTime decimal(default 3600) - Expiration time (in seconds) of the tokens if the token endpoint response does not contain an
expires_infield
- 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 token endpoint
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which are used to call the token endpoint
oauth2: SecureSocket
Represents the SSL/TLS configurations.
Fields
- disable boolean(default false) - Disable SSL validation
- cert TrustStore|string? - Configurations associated with the
crypto:TrustStoreor single certificate file that the client trusts
Errors
oauth2: Error
Represents the error type of the module. This will be returned if an error occurred while the listener OAuth2 provider tries to validate the received credentials and the client OAuth2 provider tries to generate the token.
Union types
oauth2: ClientAuth
ClientAuth
Represents the the authentication configuration types for the HTTP client used for token introspection.
oauth2: GrantConfig
GrantConfig
Represents the grant type configurations supported for OAuth2.