Authorization code

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.

sequenceDiagram
    participant U as User
    Note right of U: Authorize flow
    participant UA as UserAgent
    participant F as Front
    participant B as BFF
    participant A as Authn
    participant M as MasStack
    U->> F: Access https://company_domain/*
    F->> F: get PKCE (optional)
    F->> A: POST /oauth/authorize
    A-->> F: HTTP redirect
    F-->> UA: Open login page
    UA->> A: Get login page
    A-->> UA: Return login page
    UA->> UA: Display login page
    U->> UA: provide credentials
    UA->> A: submit login
    A->> A: validate credentials
    A->> A: create session
    A-->> UA: 302 location with code
    Note right of UA: Get token flow
    UA->> F: Follow redirect code
    F->> A: /oauth/ token with code
    A-->> F: access_token
    F->> F: save access_token in Memory
    F->> B: /api/test with header with accessToken
    B->> M: /api/test with header with accessToken
    M-->> B: response
    B-->> F: response

Warning

To use this authentication method, an authorization code client must be created. Clients are provided by the MasStack team after carefully auditing each use case, so please contact your MasStack representative to obtain your client. The minimum requirements to add in a Jira ticket are:

Title: Request to get the token in
Environment: Create one ticket per environmnent
Redirect_uri: Url where the response will be redirected with the “code”, it is recommended https://{{yourdomain}}/callback
Grant-type: In this case is “authorization_code”
If it is for custumers or for login against google

How to obtain an access_token

Step 1

Obtain the authorization code client

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:

json

{
  "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.

Step 2

Request authorization

Name	Description
authn_host	is the authn host for the desired environment.
client_id	is the id which you obtain from Authn’s team.
redirect_uri	is the HTTP endpoint on your server that will receive the response from Authn. The value must exactly match one of the authorized redirect URIs configured for Oauth 2.0. client. If this value doesn’t match an authorized URI, the request will return a 401 response error.
state	is the value commonly used to avoid CSRF attacks. This value should contain an anti-forgery unique session token, as well as any other information needed to recover the context when the user returns to your application. e.g. the starting URL. Commonly used to avoid CSRF attacks.
login_hint	(Optional) (Only support Google and Azure AD provider): If your application knows which user is trying to authenticate, it can use this parameter to provide a hint to the Authentication Server. The server uses the hint to simplify the login flow either by prefilling the email field in the sign-in form or by selecting the approprieate multi-login session.Set the parameter value to an email address or sub-identifier, which is equivalent to the user’s Google ID or Azure Active Directory.
groups_hint	(Optional)(Only support Google provider): The substring is equivalent to the groups in the provider (only support Google provider). If a groups_hint is not provided and the user is currently logged in, in the next request of token, the access_token will not contain claim groups.
access_type	(Optional) Allowed values are `online` and `offline`. If an access token is requested, the client does not receive a refresh token unless value `offline` is specified.
code_challenge	(Optional)(Recommended): Specifies an encoded `code_verifier` that will be used as a server-side challenge during authorization code exchange. This string helps mitigating against the threat usually through the use of Proof Key for Code Exchange (PKCE).
code_challenge_method	(Optional)(Recommended): Specifies what method has been used to encode a `code_verifier` that will be used during authorization code exchange. This parameter must be used with the `code_challenge` parameter. The only supported values are `S256` or `plain`. The value of code_challenge_method is plain by default if is not specified in a request that include a code_challenge.

shell


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'

Step 3

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.

Step 4

Redirect url

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

plaintext

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

Step 5

Request access token

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)

Name	Description
grant_type	parameter defines the OAuth2 flow that is going to be used; in this case, `authorization_code`
code	is the autogenerated queryparam that Authn returned in the redirect url in step 3
client_id	is the id which you obtain from Authn’s team.
redirect_uri	is the HTTP endpoint on your server that will receive the response from Authn. The value must exactly match one of the authorized redirect URIs configured for Oauth 2.0. client. If this value doesn’t match an authorized URI, the request will return a 401 response error.
code_verifier	(Optional) With the `code_challenge_method=plain` or blank the value is the same as the previous parameter used in `code_challenge`. With the `code_challenge_method=S256` the value is the original crypto random string. This value is used to confirm that the client that generated it is the same as the one requesting the access_token.

shell

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

Name	Description
grant_type	is the client grant type for token request flow. In this case, is always `authorization_code`
code	is the autogenerated queryparam that Authn returned in the redirect url in step 3
client_id	is the id which you obtain from Authn’s team.
redirect_uri	is the HTTP endpoint on your server that will receive the response from Authn. The value must exactly match one of the authorized redirect URIs configured for Oauth 2.0. client. If this value doesn’t match an authorized URI, the request will return a 401 response error.

shell


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:

Name	Description
access_token	is a signed JWT used by a user to authenticate himself against Istio’s service mesh.
refresh_token	is a signed JWT whose main goal is to obtain a new access_token without repeating customer authentication once the user has an active session.
expires_in	is the time that the access_token will be valid. Once it expires, the access_token won’t be valid and the user won’t be able to authenticate with it.
token_type	defines the type of the access_token that has been generated. This will normally be used in the Authorization header to indicate which kind of authentication has the request.

json

{
  "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).

sequenceDiagram
    participant U as User
    Note right of U: Authorize flow
    participant UA as UserAgent
    participant F as Front
    participant B as BFF
    participant A as Authn
    participant M as MasStack
    U->> F: Access https://company_domain/*
    F->> B: /api/company_domain header with accessToken
    B->> M: /mas-whatever/vx/company_domain header with accessToken
    M-->>B: HTTP-401
    B-->> F: HTTP-401
    F->> F: get PKCE (optional)
    F->> A: POST /oauth/authorize
    rect rgb(255, 240, 204, 0.75)
      A->> A: validate session ok
    end
    A-->> UA: 302 location with code
    Note right of UA: Get token flow
    UA->> F: Follow redirect code
    F->> A: /oauth/ token with code
    A-->> F: access_token
    F->> F: save access_token in Memory
    F->> B: /api/test with header with accessToken
    B->> M: /api/test with header with accessToken
    M-->> B: response
    B-->> F: response

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.

sequenceDiagram
    participant U as User
    Note right of U: Authorize flow
    participant UA as UserAgent
    participant F as Front
    participant B as BFF
    participant A as Authn
    participant M as MasStack
    U->> F: Access https://company_domain/*
    F->> B: /api/test with header with accessToken
    B->> M: /api/test with header with accessToken
    M-->> B: HTTP-401
    B-->> F: HTTP-401
    F->> F: get PKCE (optional)
    F->> A: POST /oauth/authorize
    rect rgb(255, 240, 204, 0.75)
      A->> A: validate session failed
    end
    A-->> F: HTTP redirect
    F-->> UA: Open login page
    UA->> A: Get login page
    A-->> UA: Return login page
    UA->> UA: Display login page
    U->> UA: provide credentials
    UA->> A: submit login
    A->> A: validate credentials
    A->> A: create session
    A-->> UA: 302 location with code
    Note right of UA: Get token flow
    UA->> F: Follow redirect code
    F->> A: /oauth/ token with code
    A-->> F: access_token
    F->> F: save access_token in Memory
    F->> B: /api/test with header with accessToken
    B->> M: /api/test with header with accessToken
    M-->> B: response
    B-->> F: response

Logout

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

plaintext

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

Name	Description	Mandatory
client_id	is the identifier of the client representing the app.	yes
continue	is the url to be redirected to after logout.	no
scope	if the value is all, it will delete all the user’s sessions and refresh_tokens that it has.	no

Get a token with Authorization code