Get a token with Authorization code

Authorization code authentication is the Oauth2 flow used primarily for users that want access to login in a web or app. Users must login through agent type clients with authorization code grant type. This authentication flow is the recommended because the client does not need to manage the resource owner’s (end user) credentials. Instead, it is the authorization server itself the one and only responsible of managing those credentials.

Authorization code Authentication flow

This graph shows the different flows involved in obtaining the access token.

How to obtain an access_token

Authorization Code Clients can be provided by the MasStack Owners. This team must be contacted in order to get client_id and client_secret.

When a client is created, Authn will provide:

1
2
3
4

{
    "client_id": "Rgj3HJDSV6M62nv",
    "client_secret": "Pkchr74bloe99vwcvKAPFGDF61W55XzV="
}

It is a good practice to store this parameters in different variables in order to have quickly access to this information because it will be needed in next steps.

1
2
3
4
5

curl -X GET 'https://{{authn_host}}/oauth/authorize \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id={{client_id}}&response_type=code&state={{state_token}}&code_challenge={{code_challenge_token}}&code_challenge_method={{code_challenge_method}}&redirect_uri={{redirect_uri}}&access_type=online'

After authorize request Authn will redirect to the authentication provider’s default login page (p.e.:Google login page). Users will put their credentials in it and log in.

If credentials are valid, Authn will redirect to the indicated redirect_uri with the autogenerated query param code and the state:

https://{{redirect_uri}}?code=TgradaHhSEOIhe2pEAzS9A&state=DA05F7AF-E07E-413E-B6DA-23DE26600592

To get an access token a POST request with code obtained is needed. There are two options to create this request:

Option 1: With PKCE (recommended)

1
2
3
4

curl -X POST https://{{authn_host}}/oauth/token
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=TgradaHhSEOIhe2pEAzS9A&client_id=<client_id>&redirect_uri=<redirect_uri>&code_verifier=<code_verifier>'

Option 2: With client_secret

1
2
3
4
5

curl -X POST https://{{authn_host}}/oauth/token
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=TgradaHhSEOIhe2pEAzS9A&client_id={{client_id}}&client_secret={{client_secret}}&redirect_uri={{redirect_uri}}'

If everything worked as expected, you should get this response:

1
2
3
4
5
6

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjAwNjEyN2U5LWZiYTgtNGNmNC1iYzlhLTRjNmUzODQ2MWQwMSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJBdWRpZW5jZSIsImNpZCI6IlR0c2RtZWJQY1F0RW52THNLdzd4IiwiZXhwIjoxNTU5MjI4MjI4LCJncm91cHMiOlsiY3VzdG9tZXIiXSwiaWF0IjoxNTU5MjI0NjI4LCJpc3MiOiJsdW1pZXJlZmlyZWl2YW4uYXV0aC5tYXNtb3ZpbC5jb20iLCJzY29wZXMiOiJhcGk6ZXZlcnl0aGluZyIsInN1YiI6IjYyMjYwNzc1NyIsInRpZCI6IjZlN2IxNzJmLTIyNjUtNDY1Mi1hYTI5LWVmM2EwOGI5YTYwZCJ9.ZgbFsuLXL1cnUYhJFk6IevhSkHsgVDks6b7xFYePjLZQ0Cu2itz61qJVr7bi3uN0YNTtmbaTtnkdOn6KJAjEAOYT0fIsA2MI_84bds0uP6niuDaibfWa-C_mmErxS9VcXe5cTsLwvl11gmvHeq05vszT8JN5vTXRn_MIK_lYGifG0tmFWFlB-_d409jF4KytVXMM5oqvaNAb7sZBK6RefrVTkHFEvx0U0g3F1WvtpBYGAIFksfn45BHPMEyXIXgRpsH0iJ6fwEacwwOTsaLDxmU57CumuCLxRE18KcIIdAKcgKlA1LROB-Y7Vx_YRQBXRmV2RvarGKy__Bm6RcA7qw",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjAwNjEyN2U5LWZiYTgtNGNmNC1iYzlhLTRjNmUzODQ2MWQwMSIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJUdHNkbWViUGNRdEVudkxzS3c3eCIsImV4cCI6MTU1OTMxMTAyOCwiaWF0IjoxNTU5MjI0NjI4LCJ0aWQiOiI2ZTdiMTcyZi0yMjY1LTQ2NTItYWEyOS1lZjNhMDhiOWE2MGQifQ.TPF-w5uwmvpCNB7_U9DHy6hKQUkr604FiKZtl7c1qrQ6mZ1lzate-6xc755DBqgol9mVUTfV3zz1Vgo7DbAsMiJgjL7pMydOzFW7Z9OYCsRodIBIkoX0bVo0x1Hj-51xOo5OplKI5thpwiLj4JaerJU-bFSW6CsY3SkuWwUVYvnsGafxAQlMAigd9wbySMvSb-2zbWdX18nkbByoZ-bV9z_-atW3aPafZLOdwLU4rt1voQV4mCh7MD45-sFD4NeIp922Y5T2GyDV6dVdK77Tv5f16OvuBEaprHaPAeL-vuuAP9IPqj1J7Gt0Jcmt4wfVORIxbJpWpwMa5G8sxD6zww",
  "token_type": "Bearer"
}

Access token expired with the user in session

In this graph can be seen the sequence followed when an access token expires and the user remains in session. When this occurs is not needed that the user put its credentials again.

If a request to MasStack api fails due to access token expiration, the flow to get a new access token will start again. Here the difference with first token obtention is that when authorize request is done (Step 2), the user session is validated and Authn will redirect to redirect_uri (Step 4). Next step will be to request the access token (Step 5).

Access token expired without the user in session

In this graph can be seen the sequence followed to the obtention of a new access token when it expires and the user is not in session. User is required to login again.

If a request to MasStack api fails due to access token expiration, the flow to get a new access token will start again. After authorize request is done (Step 2), user’s session validation fails and Authn will redirect to the provider’s login page to put credentials again (Step 3). Flow to get the access token continues as if it were obtained for first time.

Logout

For logins that have been made through the authorization-code oauth flow, logouts can be made through a call to:

https://{{authn_host}}/oauth/logout?client_id={{client_id}}&continue={{url}}&scope=all