Grant types

Application grant types (or flows) are methods that allow you to give applications Access tokens and grant another entities limited access to your resources without exposing credentials.

GoSpeech supports the following grant types for the integration:

• Resource owner password
• Client credentials
• Authorization code

Scopes

Scope is a mechanism in OAuth 2.0 for limiting the access of applications to user accounts. An application can request one or more scopes, and the access token issued to the application is limited to the scopes granted.

The GoSpeech application has several scopes:

• integrated-api - (required) grants access to the GoSpeech API for user actions. For instance, listing records from the Worklist.
• managed-api - grants access to control Managed Users. For instance, creation of a new managed user.
• openid - (required) returns the sub claim that uniquely identifies the user.
• email - returns claims that represent basic profile information, including name, family_name, given_name, etc.
• offline_access - extend a token response with a refresh token that you can use to get a new access token.

OAuth 2.0 Flows

Resource owner password flow

It's a straightforward flow that doesn't require multiple steps or redirections to authenticate the user.

🚧

Restrictions in GoSpeech

Due to security considerations the Resource owner password flow only allows to either authenticate a Developer or Managed Users related to the developer. It is restricted to authenticate regular users using this flow.

Pros:

• Simplicity: Easy to configure and start using.
• Direct control: The application has direct control over the user interface for authentication, allowing for a more integrated and seamless user experience.

Cons:

• Security Risks: The application directly processes user credentials, increasing the risk of security breaches. If the security of the application is compromised, the user's credentials are also at risk.
• Limited Use Cases: Not suitable for web clients.

Please follow the subsequent steps to use the Resource owner password flow :

1. Configure the API client with the Resource owner password grant type.
2. Get an access token using the token endpoint with your Client Id, Client Secret and Username, the parameter forgrant_type is password.

Client credentials flow

The Client Credentials OAuth 2.0 flow is designed for server-to-server authentication, whereby the client is also the resource owner. It's a two-stage OAuth flow that doesn't involve user authentication.

📘

Usage in GoSpeech

In GoSpeech, this flow is required to access Management API as it does not require any user context and is designed for server-to-server authentication. The API is only available for client credentials flow.

📘

Note

The Management API includes the following requests:

• List managed users
• Create managed user
• Get managed user
• Update managed user
• Delete user

Pros:

• Simplicity: It's a straightforward flow tha is easy to implement for scenarios in which the client is the resource owner.
• Performance: As no user interaction is required, latency times are reduced and server-to-server communication is improved.
• Security: The client credentials are not exposed during requests and the access tokens can be short-lived to mitigate the risk of a token leak.

Cons:

• Limited Use Case: It's only suitable for applications where the client is also the resource owner. Thus it's not designed for scenarios involving third-party user permissions.
• No User Context: The flow doesn't provide user context, which means it cannot be used for operations that require user identity or permissions.

In GoSpeech, this flow matches the Resource Owner Password as it allows to create Managed Users and authenticate them with Resource Owner Password flow. To use the flow you should follow the steps below:

1. Configure the API client with Client credentials and resource owner password grant type.
2. Get access token using token endpoint with your Client Id, Client Secret and Username, the grant_type parameter is client_credentials.

Authorization code flow with PKCE

The Authorization Code flow in OAuth 2.0 is particularly well-suited for server-side applications where the source code is not exposed and the client secrets can be kept confidential.

Pros:

• Security: It's considered the most secure flow because the access token is obtained through a back-channel. Furthermore, the authorization code on its own is useless.
• Refresh Tokens: This flow allows the issue of refresh tokens that enable long-term access without the user having to re-authenticate.

Cons:

• Complexity: It involves multiple steps, including redirects, which can make the flow more complex to implement compared to other flows.
• Mobile and Native Apps: This flow can be considered less ideal for native mobile apps, as they rely on redirects that may not work as smoothly in mobile environments.

To use the flow, you should follow the subsequent steps:

1. Configure the API client with Authorizarion code grant type.
2. Configure Authorized origins, Authorized redirect URLs, Authorized post logout redirect URLs in the API client.
3. Get an access token for users by following the steps in the diagram below.