oauth2
Module oauth2
Declarations
![](https://bcentral-packageicons.azureedge.net/images/ballerina_oauth2_2.2.1.png)
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![](/images/permalink.svg)
oauth2: ClientOAuth2Provider![](/images/permalink.svg)
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![](/images/permalink.svg)
Provides authorization based on the provided OAuth2 configurations.
init (GrantConfig grantConfig)
- grantConfig GrantConfig - OAuth2 grant type configurations
generateToken![](/images/permalink.svg)
Get an OAuth2 access token from the token endpoint.
string token = check provider.generateToken();
oauth2: ListenerOAuth2Provider![](/images/permalink.svg)
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![](/images/permalink.svg)
Provides authorization based on the provided introspection configurations.
init (IntrospectionConfig introspectionConfig)
- introspectionConfig IntrospectionConfig - Introspection endpoint configurations
authorize![](/images/permalink.svg)
function authorize(string credential, map<string>? optionalParams) returns IntrospectionResponse|Error
Validates 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:IntrospectionResponse
if the validation is successful or else anoauth2:Error
if an error occurred
Enums![](/images/permalink.svg)
oauth2: CredentialBearer![](/images/permalink.svg)
Represents the credential-bearing methods.
Members
oauth2: HttpVersion![](/images/permalink.svg)
Represents the HTTP versions.
Members
Records![](/images/permalink.svg)
oauth2: CertKey![](/images/permalink.svg)
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![](/images/permalink.svg)
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![](/images/permalink.svg)
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_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 token endpoint
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which are used to call the token endpoint
oauth2: IntrospectionConfig![](/images/permalink.svg)
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
exp
field
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which call the introspection endpoint
oauth2: IntrospectionResponse![](/images/permalink.svg)
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![](/images/permalink.svg)
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_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 token endpoint
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which are used to call the token endpoint
oauth2: PasswordGrantConfig![](/images/permalink.svg)
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_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 token endpoint
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which are used to call the token endpoint
oauth2: RefreshTokenGrantConfig![](/images/permalink.svg)
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_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 token endpoint
- clientConfig ClientConfiguration(default {}) - HTTP client configurations, which are used to call the token endpoint
oauth2: SecureSocket![](/images/permalink.svg)
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
Errors![](/images/permalink.svg)
oauth2: Error![](/images/permalink.svg)
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![](/images/permalink.svg)
oauth2: ClientAuth![](/images/permalink.svg)
ClientAuth
Represents the the authentication configuration types for the HTTP client used for token introspection.
oauth2: GrantConfig![](/images/permalink.svg)
GrantConfig
Represents the grant type configurations supported for OAuth2.
Import
import ballerina/oauth2;
Metadata
Released date: over 2 years ago
Version: 2.2.1
License: Apache-2.0
Compatibility
Platform: java11
Ballerina version: 2201.0.1
Pull count
Total: 632762
Current verison: 89100
Weekly downloads
Keywords
security
authorization
introspection
Contributors