The authentication code flow is used by applications that are hosted on a secure server. A critical aspect of the authorization code flow is that the server must be able to protect the issued client application's secret. The below figure illustrates the workflow of authorization code flow:
- A user goes on to a web application (OAuth client) in their browser and tries to access a service on the backend.
- The web application redirects the browser to an authorization server, which asks the user to give access permission for this web application. If the user accesses this request, an authorization code will be sent back to the web application.
- The web application exchanges the received authorization code to an access token at the authorization server.
- The web application accesses the resource server using this access token on behalf of the user.
To integrate your web server application with TogoID, follow the below steps:
Before integrating with TogoID, you’ll need to register the new OAuth2 application with TogoID as described in Raising an integration request. The Togo ID server assigns a
client secret. This client ID is unique for your application.
If you already have an OAuth 2.0 system in place, you may need to configure the following settings:
- Authorize URL:
- Access Token URL:
When redirecting a user to TogoID to authorize access to your application, you’ll need to construct the authorization URL with the correct parameters and scopes.
Here’s a list of parameters you should always specify:
Identifier of client application using the Togo ID server.
An arbitrary alphanumeric number issued as a part of the generated JWT token so you can be sure the token was generated specifically for your request.
The full URL to your client’s registered redirect_uri. You are permitted to add additional query parameters, but the initial URL substring must match.
For authorization code flow, response_type should be
For authorization_code flow, the scope should always be
A string value of 16 to 32 alphanumeric characters. The state is returned to the
Optional but recommended
After successfully logging in, the user is prompted for consent to share their personal information with your application. Your application requests what information it needs in the
scope parameter. If the user fails to consent to your application’s required information, then a token will not be issued and login cannot proceed. If they choose not to consent to optional information, they may continue with login and your system can handle optional or missing non-essential properties.
If the user approves your application, TogoID will redirect them back to your
redirect_uri with a temporary
code parameter. If you specified a
state parameter in step 1, it will be returned as well. The parameter will always match the value specified in step 1. If the values don’t match, the request should not be trusted.
Once the system visits the authorize endpoint and logs in, then they’re sent to the
redirect_uri with a value for
You must parse this URL to obtain the code value. You should also verify that the state matches the state generated for the authorization request.
Client side URL parse
The fragment portion of the URL is often not sent to servers for processing. So clients must perform initial URL parsing on client side JS or mobile app code.
To obtain the
id_token (required) and
access_token (optional) you then send the
code, obtained from Step 3, back to the token endpoint. This can be done by making a POST call:
POST /connect/token HTTP/1.1 Host: id2.runswithtogo.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=Y2NmMDk2NDkxM2U2NzNjNWQ3YWQwY2M0&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=MWYzNGVjNjM3NmE5NGZiYzUwZmI3NDky&redirect_uri=https%3A%2F%2Fsample.togogroup.com%2Ftogo-callback
The authorization code returned from the initial request.
One of the redirect URIs you listed in the integration request form.
Identifier of client application using Togo ID server.
The client secret obtained from Togo Group for your application.
As defined in the OAuth 2.0 specification, this field must contain a value of
The value is a JSON Web Token (JWT) that contains digitally signed identity information about the user. For more information on parsing the ID token, see Parsing the ID token.
This token may be used by your application to authorize an API request.
The type of token returned. At this time, this field's value is always set to
The remaining lifetime of the access token in seconds.
After your application obtains an ID token, you can make your first API call. To do this, include the ID token in the API request header parameter
Authorization: Bearer <id_token>.
Updated about a year ago