OAuthServiceBuilder
Overview
The OAuthServiceBuilder object is used to configure and build OAuth services for managing authentication flows. It offers a flexible API to set up various OAuth parameters such as client secrets, scopes, response types, and token handling. Additionally, it provides advanced features like Proof Key for Code Exchange (PKCE) and anti-forgery state configuration, ensuring secure and customizable OAuth implementations.
Developers can define the required scopes, configure callback functions, and set domain or tenant information for APIs that support multi-tenant setups. The builder also supports customization of authorization URLs with additional parameters, allowing fine-grained control over the OAuth flow. Once configured, the build(api) method creates an OAuthService object, which can be used to obtain tokens and access protected resources.
For additional details about OAuth authentication, refer to the OAuth provider in the Authentication section of this documentation.
Methods Summarized
Creates an OAuth service that can be used to obtain an access token and access protected data.
Creates an OAuth service that can be used to obtain an access token and access protected data.
Configure the service with a callback function to be executed when the service is ready to use.
OPTIONAL This is a way to override the default deeplink method name, which is 'deeplink_svy_oauth'.
If a refresh token is available, the service can be configured to obtain a new access token without showing the login screen.
Configure if the code/tokens are going to be received as a query or as a url fragment.
Configures the service with Proof Key for Code Exchange, which prevents authorization code interception attacks.
Methods Detailed
additionalParameters(params)
Add some more parameters to the authorization url.
Parameters
Object params a json containing the parameters and their values e.g. {'param1': 'value1', 'param2': 'value2'}
Returns: OAuthServiceBuilder the service builder for method chaining
build(api)
Creates an OAuth service that can be used to obtain an access token and access protected data.
Parameters
CustomApiBuilder api a custom api, see plugins.oauth.customApi
Returns: OAuthService an OAuthService object that can be used to make signed requests to the api
build(api)
Creates an OAuth service that can be used to obtain an access token and access protected data.
Parameters
String api an OAuth provider id, see plugins.oauth.OAuthProviders
Returns: OAuthService an OAuthService object that can be used to make signed requests to the api
callback(callback, timeout)
Configure the service with a callback function to be executed when the service is ready to use. After the access token is returned by the server, this callback function is executed.
Parameters
Function callback a function in a scope or form
Number timeout max number of seconds in which the callback method should be executed (with success or error message) Please note that the timeout should be enough for the user to login and accept permissions.
Returns: OAuthServiceBuilder the service builder for method chaining
clientSecret(clientSecret)
Set the client secret of the application.
Parameters
String clientSecret a secret known only to the application and the authorization server
Returns: OAuthServiceBuilder the service builder for method chaining
deeplink(deeplink)
OPTIONAL This is a way to override the default deeplink method name, which is 'deeplink_svy_oauth'. The deeplink method is a global method that receives the code needed to obtain the access token from the OAuth provider. NOTE: The deeplink method name is strongly related to the redirect url configured for the application. If the OAuth provider (eg. Microsoft AD, Likedin) requires to configure a full redirect url then it should be of the form: https://example.com/<solution_name>/m/<deeplinkmethod> - where <deeplinkmethod> is the name configured with the service builder https://example.com/<solution_name>/m/deeplink_svy_oauth - if the deeplink method name was not overridden If the deeplink method with the provided name does not exist in the solution, then a default deeplink method is generated under the hood with the solution model. If a global method with the provided name already exists in the solution, then it should set the access token on the service and handle possible errors.
Parameters
String deeplink a global scope method name
Returns: OAuthServiceBuilder the service builder for method chaining
defaultScope(scope)
Request always the same scope. Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. An application can request one or more scopes, separated by space. This information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.
Parameters
String scope the default scope
Returns: OAuthServiceBuilder the service builder for method chaining
domain(domain)
Set the domain if the API supports it (e.g.Okta)
Parameters
String domain ;
Returns: OAuthServiceBuilder the service builder for method chaining
getUsedAuthorizationURL(api)
Get the authorization url. This is for DEBUGGING PURPOSES ONLY.
Parameters
CustomApiBuilder api a custom api builder
Returns: String the used authorization url
getUsedAuthorizationURL(api)
Get the authorization url. This is for DEBUGGING PURPOSES ONLY.
Parameters
String api an OAuth provider id, see plugins.oauth.OAuthProviders
Returns: String the used authorization url
refreshToken(token)
If a refresh token is available, the service can be configured to obtain a new access token without showing the login screen.
Parameters
String token the refresh token
Returns: OAuthServiceBuilder the service builder for method chaining
responseMode(mode)
Configure if the code/tokens are going to be received as a query or as a url fragment. Will be ignored if the response type is token/id_token or if the oauth provider does not support it. For the "fragment" response mode the redirect url configured for the oauth app needs to be of the following form https://example.com/servoy-service/oauth/solutions/<solution_name>/m/<deeplinkmethod> - where <deeplinkmethod> is the name configured with the service builder
Parameters
String mode can be "query" or "fragment"
Returns: OAuthServiceBuilder the service builder for method chaining
responseType(response_type)
Configures the OAuth flow. Defaults to "code" (authorization code flow) if not set. Use response type "token" for the implicit grant flow. Use response type "id_token" for OpenID Connect sign-in. In this case the response is a JWT token which can be used to verify the identity of a user. OAuth providers may allow combinations of "code" "id_token" "token".
Parameters
String response_type one or a combination of "code" "id_token" "token"
Returns: OAuthServiceBuilder the service builder for method chaining
scope(scope)
Request any unique scope per each access token request. Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. An application can request one or more scopes, separated by space. This information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.
Parameters
String scope one or multiple scopes separated by space
Returns: OAuthServiceBuilder the service builder for method chaining
state(state)
Configures the anti forgery session state. This is required in some APIs (like Facebook's).
Parameters
String state ;
Returns: OAuthServiceBuilder the service builder for method chaining
tenant(tenant)
Set the tenant identifiers/organization if the API supports it (e.g.Microsoft AD)
Parameters
String tenant ;
Returns: OAuthServiceBuilder the service builder for method chaining
withPKCE()
Configures the service with Proof Key for Code Exchange, which prevents authorization code interception attacks. See more at https://datatracker.ietf.org/doc/html/rfc7636.
Returns: OAuthServiceBuilder the service builder for method chaining
Last updated