OAuth2.0

OAuth2.0 is the most secure and widely used authorization framework used to grant third party applications controlled access to protected resources.

Iguana often acts as a Client, connecting with systems which use OAuth 2.0 authorization. There are many different types of OAuth2.0 flows, however in general, it is a multi-step process involving exchanging shared secrets to obtain a trusted access token used to access the Server’s protected resources.

Screen Shot 2024-02-20 at 12.41.01 PM.png

Of the OAuth2.0 Flows, one of the most common use cases for Iguana (server-server communication without involving user interaction) is the Client Credentials Grant. You can reference an example of this authentication flow in our Epic FHIR Adapter.

There are three key stages in this OAuth2.0 workflow:

The client application authenticates itself with the authorization server by sending authentication credentials to the authorization server's token endpoint. There are various alternative credentials including:

Client ID and Secret - these are obtained upon client registration with the server.
JSON Web Token (JWT) this is an encoded and signed JSON token that is generated by the Client to provide the authorization details that help the Server determine the Client’s identity, scope of access and contains details like access token expiry.

The OAUTH Library provides an example to help with signing JWTs using the crypto API.

The authorization server validates the client's credentials and, if successful, issues an access token directly to the client application.

To add another layer of security, access tokens can have defined scopes with specific access permissions granted by the resource owner and can expire, requiring them to be refreshed periodically.

If an access token has an expiry, this is sometimes handled by simply restarting the workflow from the Client Authentication step to request a new access token, or alternatively the application may provide a refresh token to use to exchange for a new access token.

Once the client obtains an access token, it can be used in HTTP requests to access protected resources on the resource server as proof of authorization. The access token serves as proof of authorization, allowing the client to access the resources specified in the token's scope.

When an application doesn’t support server-server communication, you can still set up the OAuth workflow and use Iguana to integrate. In this case, the OAuth client authentication and authorization grant process is completed within the application to obtain a non-expiring access token or an access token and refresh tokens. Then Iguana can use the access token to request protected resources. You can see an example of this scenario with the Slack Notifier Adapter.