diff --git a/ballerina/client_oauth2_provider.bal b/ballerina/client_oauth2_provider.bal index 297c1782..6d1992de 100644 --- a/ballerina/client_oauth2_provider.bal +++ b/ballerina/client_oauth2_provider.bal @@ -20,17 +20,17 @@ import ballerina/url; const UTF8 = "UTF-8"; -# Represents the data structure, which is used to configure the OAuth2 client credentials grant type. +# The configurations for the OAuth2 client credentials grant type. # -# + tokenUrl - Token URL of the token endpoint -# + clientId - Client ID of the client authentication -# + clientSecret - Client secret of the client authentication -# + scopes - Scope(s) of the access request -# + defaultTokenExpTime - Expiration time (in seconds) of the tokens if the token endpoint response does not contain an `expires_in` field -# + clockSkew - Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems -# + optionalParams - Map of the optional parameters used for the token endpoint -# + credentialBearer - Bearer of the authentication credentials, which is sent to the token endpoint -# + clientConfig - HTTP client configurations, which are used to call the token endpoint +# + tokenUrl - The URL of the token endpoint +# + clientId - The client ID of the client authentication +# + clientSecret - The client secret of the client authentication +# + scopes - The scope(s) of the access request. This can be a single string or an array of strings +# + defaultTokenExpTime - The default expiration time (in seconds) for tokens if the token endpoint response does not include an `expires_in` field +# + clockSkew - The clock skew (in seconds) to account for clock synchronization issues +# + optionalParams - A map of optional parameters to be sent to the token endpoint +# + credentialBearer - The bearer type for authentication credentials sent to the token endpoint +# + clientConfig - HTTP client configurations used to make requests to the token endpoint public type ClientCredentialsGrantConfig record {| string tokenUrl; string clientId; @@ -46,13 +46,13 @@ public type ClientCredentialsGrantConfig record {| # Constant used to infer the values of refreshConfig from values provided for PasswordGrantConfig. public const INFER_REFRESH_CONFIG = "INFER_REFRESH_CONFIG"; -# Represents the data structure, which is used for refresh configuration of the OAuth2 password grant type. +# The refresh configurations for the OAuth2 password grant type. # -# + refreshUrl - Refresh token URL of the token endpoint -# + scopes - Scope(s) of the referesh token request -# + optionalParams - Map of the optional parameters used for the token endpoint -# + credentialBearer - Bearer of the authentication credential, which is sent to the token endpoint -# + clientConfig - HTTP client configuration, which is used to call the refresh token endpoint +# + refreshUrl - The URL of the refresh token endpoint +# + scopes - The scope(s) of the refresh token request. This can be a single string or an array of strings +# + optionalParams - A map of optional parameters to be sent to the refresh token endpoint +# + credentialBearer - The bearer type for authentication credentials sent to the refresh token endpoint +# + clientConfig - HTTP client configurations used to make requests to the refresh token endpoint public type RefreshConfig record {| string refreshUrl; string|string[] scopes?; @@ -61,20 +61,20 @@ public type RefreshConfig record {| ClientConfiguration clientConfig = {}; |}; -# Represents the data structure, which is used to configure the OAuth2 password grant type. +# The configurations for the OAuth2 password grant type. # -# + tokenUrl - Token URL of the token endpoint -# + username - Username for the password grant type -# + password - Password for the password grant type -# + clientId - Client ID of the client authentication -# + clientSecret - Client secret of the client authentication -# + scopes - Scope(s) of the access request -# + refreshConfig - Configurations for refreshing the access token -# + defaultTokenExpTime - Expiration time (in seconds) of the tokens if the token endpoint response does not contain an `expires_in` field -# + clockSkew - Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems -# + optionalParams - Map of the optional parameters used for the token endpoint -# + credentialBearer - Bearer of the authentication credentials, which is sent to the token endpoint -# + clientConfig - HTTP client configurations, which are used to call the token endpoint +# + tokenUrl - The URL of the token endpoint +# + username - The username for the password grant type +# + password - The password for the password grant type +# + clientId - The client ID for client authentication +# + clientSecret - The client secret for client authentication +# + scopes - The scope(s) of the access request. This can be a single string or an array of strings +# + refreshConfig - The configurations for refreshing the access token. Can be a `RefreshConfig` or `oauth2:INFER_REFRESH_CONFIG` +# + defaultTokenExpTime - The default expiration time (in seconds) for tokens if the token endpoint response does not include an `expires_in` field +# + clockSkew - The clock skew (in seconds) to account for clock synchronization issues +# + optionalParams - A map of optional parameters to be sent to the token endpoint +# + credentialBearer - The bearer type for authentication credentials sent to the token endpoint +# + clientConfig - HTTP client configurations used to make requests to the token endpoint public type PasswordGrantConfig record {| string tokenUrl; string username; @@ -90,18 +90,18 @@ public type PasswordGrantConfig record {| ClientConfiguration clientConfig = {}; |}; -# Represents the data structure, which is used to configure the OAuth2 refresh token grant type. +# The configurations for the OAuth2 refresh token grant type. # -# + refreshUrl - Refresh token URL of the token endpoint -# + refreshToken - Refresh token for the token endpoint -# + clientId - Client ID of the client authentication -# + clientSecret - Client secret of the client authentication -# + scopes - Scope(s) of the access request -# + defaultTokenExpTime - Expiration time (in seconds) of the tokens if the token endpoint response does not contain an `expires_in` field -# + clockSkew - Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems -# + optionalParams - Map of the optional parameters used for the token endpoint -# + credentialBearer - Bearer of the authentication credentials, which is sent to the token endpoint -# + clientConfig - HTTP client configurations, which are used to call the token endpoint +# + refreshUrl - The URL of the refresh token endpoint +# + refreshToken - The refresh token used to obtain a new access token +# + clientId - The client ID for client authentication +# + clientSecret - The client secret for client authentication +# + scopes - The scope(s) of the access request. This can be a single string or an array of strings +# + defaultTokenExpTime - The default expiration time (in seconds) for tokens if the token endpoint response does not include an `expires_in` field +# + clockSkew - The clock skew (in seconds) to account for clock synchronization issues +# + optionalParams - A map of optional parameters to be sent to the token endpoint +# + credentialBearer - The bearer type for authentication credentials sent to the token endpoint +# + clientConfig - HTTP client configurations used to make requests to the token endpoint public type RefreshTokenGrantConfig record {| string refreshUrl; string refreshToken; @@ -115,18 +115,18 @@ public type RefreshTokenGrantConfig record {| ClientConfiguration clientConfig = {}; |}; -# Represents the data structure, which is used to configure the OAuth2 JWT bearer grant type. +# The configurations for the OAuth2 JWT bearer grant type. # -# + tokenUrl - Token URL of the token endpoint -# + assertion - A single JWT for the JWT bearer grant type -# + clientId - Client ID of the client authentication -# + clientSecret - Client secret of the client authentication -# + scopes - Scope(s) of the access request -# + defaultTokenExpTime - Expiration time (in seconds) of the tokens if the token endpoint response does not contain an `expires_in` field -# + clockSkew - Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems -# + optionalParams - Map of the optional parameters used for the token endpoint -# + credentialBearer - Bearer of the authentication credentials, which is sent to the token endpoint -# + clientConfig - HTTP client configurations, which are used to call the token endpoint +# + tokenUrl - The URL of the token endpoint +# + assertion - A single JWT used for the JWT bearer grant type +# + clientId - The client ID for client authentication +# + clientSecret - The client secret for client authentication +# + scopes - The scope(s) of the access request. This can be a single string or an array of strings +# + defaultTokenExpTime - The default expiration time (in seconds) for tokens if the token endpoint response does not include an `expires_in` field +# + clockSkew - The clock skew (in seconds) to account for clock synchronization issues +# + optionalParams - A map of optional parameters to be sent to the token endpoint +# + credentialBearer - The bearer type for authentication credentials sent to the token endpoint +# + clientConfig - HTTP client configurations used to make requests to the token endpoint public type JwtBearerGrantConfig record {| string tokenUrl; string assertion; @@ -140,7 +140,7 @@ public type JwtBearerGrantConfig record {| ClientConfiguration clientConfig = {}; |}; -// The data structure, which stores the values needed to prepare the HTTP request, which are to be sent to the +// Represents the values needed to prepare the HTTP request, which are to be sent to the // token endpoint. type RequestConfig record {| string payload; @@ -151,10 +151,10 @@ type RequestConfig record {| CredentialBearer credentialBearer; |}; -# Represents the grant type configurations supported for OAuth2. +# The grant type configurations supported for OAuth2. public type GrantConfig ClientCredentialsGrantConfig|PasswordGrantConfig|RefreshTokenGrantConfig|JwtBearerGrantConfig; -# Represents the client OAuth2 provider, which is used to generate OAuth2 access tokens using the configured OAuth2 +# 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. # @@ -197,7 +197,11 @@ public isolated class ClientOAuth2Provider { # Provides authorization based on the provided OAuth2 configurations. # - # + grantConfig - OAuth2 grant type configurations + # + grantConfig - The OAuth2 grant type configurations. This can be one of the following: + # - `ClientCredentialsGrantConfig`: Configuration for the client credentials grant type. + # - `PasswordGrantConfig`: Configuration for the password grant type. + # - `RefreshTokenGrantConfig`: Configuration for the refresh token grant type. + # - `JwtBearerGrantConfig`: Configuration for the JWT bearer grant type. public isolated function init(GrantConfig grantConfig) { self.grantConfig = grantConfig.cloneReadOnly(); self.tokenCache = new; @@ -208,12 +212,12 @@ public isolated class ClientOAuth2Provider { } } - # Get an OAuth2 access token from the token endpoint. + # Gets an OAuth2 access token from the token endpoint. # ```ballerina # string token = check provider.generateToken(); # ``` # - # + return - Received OAuth2 access token or else an `oauth2:Error` if an error occurred + # + return - The received OAuth2 access token as a `string` or an `oauth2:Error` if an error occurred public isolated function generateToken() returns string|Error { string|Error authToken = generateOAuth2Token(self.grantConfig, self.tokenCache); if authToken is string { diff --git a/ballerina/listener_oauth2_provider.bal b/ballerina/listener_oauth2_provider.bal index 4e76a371..69ebd98a 100644 --- a/ballerina/listener_oauth2_provider.bal +++ b/ballerina/listener_oauth2_provider.bal @@ -18,14 +18,14 @@ import ballerina/cache; import ballerina/log; import ballerina/time; -# Represents the introspection endpoint configurations. +# The configurations for the introspection endpoint. # -# + url - URL of the introspection endpoint +# + url - The URL of the introspection endpoint # + tokenTypeHint - A hint about the type of the token submitted for introspection -# + optionalParams - Map of the optional parameters used for the introspection endpoint -# + cacheConfig - Configurations for the cache used to store the OAuth2 access token and other related information -# + defaultTokenExpTime - Expiration time (in seconds) of the tokens if the introspection response does not contain an `exp` field -# + clientConfig - HTTP client configurations, which call the introspection endpoint +# + optionalParams - A map of the optional parameters used for the introspection endpoint +# + cacheConfig - The configurations for the cache used to store the OAuth2 access token and other related information +# + defaultTokenExpTime - The default expiration time (in seconds) for tokens if the introspection response does not include an `exp` field +# + clientConfig - The HTTP client configurations used to call the introspection endpoint public type IntrospectionConfig record { string url; string tokenTypeHint?; @@ -35,20 +35,20 @@ public type IntrospectionConfig record { ClientConfiguration clientConfig = {}; }; -# Represents the introspection endpoint response. +# The introspection endpoint response type. # -# + active - Boolean indicator of whether or not the presented token is currently active +# + active - A boolean indicating whether the presented token is currently active # + scope - A JSON string containing a space-separated list of scopes associated with this token -# + clientId - Client identifier for the OAuth 2.0 client, which requested this token -# + username - Resource owner who authorized this token -# + tokenType - Type of the token -# + exp - Expiry time (seconds since the Epoch) -# + iat - Time when the token was issued originally (seconds since the Epoch) -# + nbf - Token is not to be used before this time (seconds since the Epoch) -# + sub - Subject of the token -# + aud - Intended audience of the token -# + iss - Issuer of the token -# + jti - String identifier for the token +# + clientId - The client identifier for the OAuth 2.0 client that requested this token +# + username - The resource owner who authorized this token +# + tokenType - The type of the token +# + exp - The expiration time of the token (in seconds since the Epoch) +# + iat - The time when the token was issued (in seconds since the Epoch) +# + nbf - The time before which the token must not be used (in seconds since the Epoch) +# + sub - The subject of the token +# + aud - The intended audience of the token +# + iss - The issuer of the token +# + jti - A unique identifier for the token public type IntrospectionResponse record { boolean active; string scope?; @@ -78,7 +78,7 @@ const string AUD = "aud"; const string ISS = "iss"; const string JTI = "jti"; -# Represents the listener OAuth2 provider, which is used to validate the received credential (access token) by +# The listener for the OAuth2 provider, which is used to validate the received credential (access token) by # calling the configured introspection endpoint. # ```ballerina # oauth2:IntrospectionConfig config = { @@ -111,13 +111,13 @@ public isolated class ListenerOAuth2Provider { } } - # Validates the provided OAuth2 acess token against the introspection endpoint. + # Validates the provided OAuth2 access token against the introspection endpoint. # ```ballerina # boolean result = check provider.authorize(""); # ``` # - # + credential - OAuth2 access token to be validated - # + optionalParams - Map of the optional parameters used for the introspection endpoint + # + credential - The OAuth2 access token to be validated + # + optionalParams - A map of optional parameters to be sent to the introspection endpoint # + return - An `oauth2:IntrospectionResponse` if the validation is successful or else an `oauth2:Error` if an error occurred public isolated function authorize(string credential, map? optionalParams = ()) returns IntrospectionResponse|Error { if credential == "" { diff --git a/ballerina/oauth2_commons.bal b/ballerina/oauth2_commons.bal index a722ae9a..fcbc9ace 100644 --- a/ballerina/oauth2_commons.bal +++ b/ballerina/oauth2_commons.bal @@ -17,11 +17,11 @@ import ballerina/crypto; import ballerina/jballerina.java; -# Represents the configurations of the client used to call the introspection endpoint. +# The configurations of the client used to call the introspection endpoint. # # + httpVersion - The HTTP version of the client -# + customHeaders - The list of custom HTTP headers -# + customPayload - The list of custom HTTP payload parameters +# + customHeaders - A map of custom HTTP headers to be included in the request +# + customPayload - A custom HTTP payload to be sent with the request # + auth - The client auth configurations # + secureSocket - SSL/TLS-related configurations # + connectTimeout - Maximum time(in seconds) to wait for a connection to be established. By default, uses the global @@ -38,16 +38,16 @@ public type ClientConfiguration record {| decimal reqTimeout?; |}; -# Represents the the authentication configuration types for the HTTP client used for token introspection. +# The authentication configuration types for the HTTP client used for token introspection. public type ClientAuth ClientCredentialsGrantConfig|PasswordGrantConfig|RefreshTokenGrantConfig; -# Represents the HTTP versions. +# The HTTP versions. public enum HttpVersion { HTTP_1_1, HTTP_2 } -# Represents the SSL/TLS configurations. +# The SSL/TLS configurations. # # + disable - Disable SSL validation # + cert - Configurations associated with the `crypto:TrustStore` or single certificate file that the client trusts @@ -58,7 +58,7 @@ public type SecureSocket record {| crypto:KeyStore|CertKey key?; |}; -# Represents the combination of the certificate file path, private key file path, and private key password if encrypted. +# The combination of the certificate file path, private key file path, and private key password if encrypted. # # + certFile - A file containing the certificate # + keyFile - A file containing the private key @@ -69,7 +69,7 @@ public type CertKey record {| string keyPassword?; |}; -# Represents the credential-bearing methods. +# The credential-bearing methods. public enum CredentialBearer { AUTH_HEADER_BEARER, POST_BODY_BEARER diff --git a/ballerina/oauth2_errors.bal b/ballerina/oauth2_errors.bal index 72e68cf8..9c6a5c89 100644 --- a/ballerina/oauth2_errors.bal +++ b/ballerina/oauth2_errors.bal @@ -16,7 +16,7 @@ import ballerina/log; -# Represents the error type of the module. This will be returned if an error occurred while the listener OAuth2 provider +# 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. public type Error distinct error;