Implementing OAuth2 and OpenID Connect for Secure API Communication

Developers
1

Introduction

Welcome to the Empress OAuth2 and OpenID Connect guide, designed to provide developers with a comprehensive guide to integrating and utilizing these authentication protocols. OAuth2 and OpenID Connect are critical for secure API communication, offering a robust framework for user authentication and data access.

Authorization and Authentication

For authenticated requests, use the header Authorization: Bearer <access_token>. You can get a bearer token by following the steps outlined in the sections below.

Getting an Authorization Code

The first step in the OAuth2 flow is to get an authorization code from the user. This allows your application to access ERPNext on behalf of the user.

Use the API endpoint GET /api/method/frappe.integrations.oauth2.authorize to achieve this.

Query Parameters:

  • client_id (string): ID of your OAuth2 application.
  • state (string): Arbitrary value used by your application to maintain state between the request and callback. This value is included when the authorization server redirects the user-agent back to your client.
  • response_type (string): “code”
  • scope (string): The access scope that should be granted to your application.
  • redirect_uri (string): Callback URI that the user will be redirected to after your application is authorized. The authorization code can be extracted from the params.

Optional:

  • code_challenge_method (string): Can be one from s256 or plain.
  • code_challenge (string): Can be base64encode(sha256(random_string)) in case code_challenge_method=s256 or random_string in case code_challenge_method=plain.

Example Request:

curl -X POST https://{your frappe instance}/api/method/frappe.integrations.oauth2.authorize \
     --data-urlencode 'client_id=511cb2ac2d' \
     --data-urlencode 'state=444' \
     --data-urlencode 'response_type=code'
     --data-urlencode 'scope=openid%20all' \
     --data-urlencode 'redirect_uri=https://app.getpostman.com/oauth2/callback'

Response:

The API will return an HTTP 200 code along with a redirection to the redirect_uri. The authorization code can be found in the redirected URI’s query parameters.

If the user chooses to deny the request, you will receive an error in the redirected URI.

Token Exchange for Authorization Code Grant with ID Token

Once you have obtained the authorization code, you can exchange it for an access token. Use the API endpoint POST /api/method/frappe.integrations.oauth2.get_token for this purpose.

Request Headers:

  • Content-Type: application/x-www-form-urlencoded

Body Parameters:

  • grant_type (string): “authorization_code”
  • code (string): Authorization code received in redirect URI.
  • client_id (string): ID of your OAuth2 application
  • redirect_uri (string): Registered redirect URI of client app

Example Request:

curl -X POST https://{your frappe instance}/api/method/frappe.integrations.oauth2.get_token \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -H 'Accept: application/json' \
     -d 'grant_type=authorization_code&amp;code=wa1YuQMff2ZXEAu2ZBHLpJRQXcGZdr
         &amp;redirect_uri=https%3A%2F%2Fapp.getpostman.com%2Foauth2%2Fcallback&amp;client_id=af615c2d3a'

Response:

The API will return a JSON object containing the access token, token type, expiration time, refresh token, scope, and ID token.

Revoke Token Endpoint

To revoke a token, use the API endpoint POST /api/method/frappe.integrations.oauth2.revoke_token.

Request Headers:

  • Content-Type: application/x-www-form-urlencoded

Body Parameters:

  • token: Access token to be revoked.

Response:

The API will return an HTTP 200 code with an empty response.

Open ID Connect id_token

The ID token is a JWT. It contains several claims including aud, iss, sub, roles, exp, and iat.

OpenID User Info Endpoint

To get user info, use the API endpoint GET /api/method/frappe.integrations.oauth2.openid_profile.

Request Headers:

  • Authorization: Bearer valid_access_token

Response:

The API will return a JSON object containing user information.

Introspect Token Endpoint

To introspect a token, use the API endpoint POST /api/method/frappe.integrations.oauth2.introspect_token.

Request Headers:

  • Content-Type: application/x-www-form-urlencoded

Body Parameters:

  • token_type_hint: access_token or refresh_token, defaults to access_token if nothing is provided
  • token: Access token or Refresh Token to be introspected. Depends on token_type_hint

Response:

The API will return a JSON object containing token information.

Conclusion

This guide has covered the OAuth2 and OpenID Connect implementation in Empress. These protocols provide a robust framework for secure API communication and user authentication in your application. By integrating these protocols into your application, you can ensure that your application’s communication with the ERPNext system is secure and reliable.