Authorization Code Grant

The OAuth 2.0 authorization code grant can be used in apps that are installed on a device to gain access to protected resources, such as web APIs. Using the Agile.Now identity platform implementation of OAuth 2.0 and Open ID Connect (OIDC), you can add sign in and API access to your mobile and desktop apps.

Request an authorization code

The authorization code flow begins with the client directing the user to the /oAuth/Authorize endpoint. In this request, the client requests the openid and name permissions from the user.

// Line breaks for legibility only

https://login.agilenow.io/oauth/authorize?
response_mode=query
&response_type=code
&redirect_uri=https%3A%2F%2Facme.com%2Fcallback%2F
&client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=openid%20name
&state=1234567890

All parameters to authorize user

In the Authorization Code Grant Flow, once the user is redirected to the Agile.Now identity platform, they will be prompted to enter their credentials and complete the authentication process. This step is crucial as it ensures the user's identity before any authorization codes are issued.

After the successful authentication, the Agile.Now identity platform sends a response back to your application using the URL specified in the redirect_uri parameter. The method of response will be determined by what is set in the response_mode parameter, ensuring flexibility and compatibility with different integration requirements.

External Authentication with Azure AD or Google

Additionally, Agile.Now offers the capability to integrate with external identity providers like Azure AD or Google OAuth2. In such scenarios, the actual authentication happens through Azure AD, not directly with Agile.Now. Users will be redirected to the Azure AD login page, where they enter their credentials and authenticate.

Once authenticated with Azure AD, the user is redirected back to Agile.Now, which handles the issuance of the authorization code and continues the flow as usual. This feature allows for enhanced security and the convenience of single sign-on (SSO), leveraging the robustness of established identity providers like Azure AD.

Remember to configure the necessary settings and establish a trust relationship between Agile.Now and Azure AD to enable this integration and ensure a seamless authentication experience for the users.

Successful response

A successful response using response_mode=query looks like:

HTTP/1.1 302 Found
https://acme.com/callback?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=1234567890
&nonce=LdgfSTLEMPGYuNHSUYB

Service returns parameters to authorize user

Error response
Error responses may also be sent to the redirect_uri so the app can handle them appropriately:

HTTP/1.1 302 Found
https://acme.com/callback?
error=invalid_request
&error_description=Client%20authentication%20failed.
&state=1234567890

Service returns parameters to authorize user

Exchange authorization code for access token

After obtaining the authorization code, exchange it for an access token by making a POST request to the /oAuth/rest/v2/Token endpoint.

POST /oAuth/rest/v2/Token HTTP/1.1
Host: login.agilenow.io:443
Content-Type: application/x-www-form-urlencoded

code=AUTHORIZATION_CODE
&client_id=CLIENT_ID
&grant_type=authorization_code

Successful response

A successful response includes an access_token and an id_token if the openid scope was requested.

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzIBP...",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

Error response

An error response (403 Permission) looks like this:

{
   "error":"Permission",
   "error_description":"The client application isn't permitted to request a 'refresh_token' code.",
   "Errors":[
     "The client application isn't permitted to request an authorization code."
   ],
   "Type":"/Errors/Permission",
   "Title":"Permission",
   "StatusCode":403,
   "Instance":"/oAuth/rest/v2/Token"
}

Use a token

Now that you've acquired a token, use the token to make requests to the resource. When the token expires, repeat the request to the /oAuth/rest/v2/Token endpoint to acquire a fresh access token.