Module oauth2
ballerina/oauth2 Ballerina library
Overview
This module provides a framework for interacting with OAuth2 authorization servers as specified in RFC 6749 and RFC 7662, enabling third-party applications to obtain limited access to HTTP services, and defines auth providers for clients and listeners of different protocol connectors.
Key Features
- Listener and Client OAuth2 providers
- Token introspection support, per RFC 7662
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
Constants
oauth2: DEFAULT_CONNECT_TIMEOUT
Represents the default connection timeout values for the oauth2 client.
oauth2: DEFAULT_REQ_TIMEOUT
Represents the default request timeout value for the oauth2 client.
oauth2: INFER_REFRESH_CONFIG
Constant used to infer the values of refreshConfig from values provided for PasswordGrantConfig.
Enums
oauth2: CredentialBearer
Represents the credential-bearing methods.
Members
oauth2: HttpVersion
Represents the HTTP versions.
Members
Configurables
oauth2: globalConnectTimeout
Represents the maximum time(in seconds) to wait for a connection to be established with the oauth2 endpoint. Defaults to 15 seconds. This is a global configuration which will be applied to all the internal oauth2 client calls.
oauth2: globalReqTimeout
Represents the maximum time(in seconds) to wait for a response before the oauth2 endpoint request times out. Defaults to 30 seconds. This is a global configuration which will be applied to all the internal oauth2 client calls.
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
- connectTimeout? decimal - Maximum time(in seconds) to wait for a connection to be established. By default, uses the global
configuration
globalConnectTimeoutwhich defaults to 15 seconds
- reqTimeout? decimal - Maximum time(in seconds) to wait for a response before the request times out. By default, uses the global
configuration
globalReqTimeoutwhich defaults to 30 seconds
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
- 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
- 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
- refreshConfig? RefreshConfig|INFER_REFRESH_CONFIG - 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: RefreshConfig
Represents the data structure, which is used for refresh configuration of the OAuth2 password grant type.
Fields
- refreshUrl string - Refresh token URL of the token endpoint
- credentialBearer CredentialBearer(default AUTH_HEADER_BEARER) - Bearer of the authentication credential, which is sent to the token endpoint
- clientConfig ClientConfiguration(default {}) - HTTP client configuration, which is used to call the refresh 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
- 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.