OAuth2.0 Grants — Cheatsheet for WSO2 Identity Server or Asgardeo

WSO2 Identity Server(IAM) is a fully OAuth2.0 and OpenID Connect compliant CIAM product that can run an on-prem or private cloud. Asgardeo is the new IDaaS(CIAM Cloud solution) offered by WSO2 to cater to all your developer-friendly CIAM needs. Both our CIAM products allow users to easily experience Single Sign-On with OpenID connect and delegate access to resources through OAuth2.0.

Asagrdeo is now open for early adoption - you can create an account for you/your organization for free and try out!

This blog will give you a simpler view of the most commonly used grant types how we can try them out even without an actual sample application like the playground.

Sample Sp name — test-sp

Callback URL used — http://testsp/callback

Main Grant Types and its Request Formats

Authorization Code Grant

This grant type is a redirection-based grant type. This grant type uses a browser redirection call as the first call to receive the code after authentication and secondly, a backchannel call to get the access token using the code received from the first browser call.

1. Browser request: Copy-paste this sample request on the browser and get the authorization code from the browser to use in the second curl command

https://{hostname:por}or{Asgardeo URL}/oauth2/authorize?response_type=code&client_id=<client-id>&nonce=oidc&redirect_uri=<call-back url>&scope=openid

Adding **scope=openid **will give you the id token in the second token response. Simply the OAuth2.0 request becomes an OpenID Connect request.

2. Back-channel request: curl command

curl -k -v --user <client-id>:<secret> 
-d "grant_type=authorization_code&code=<code recieved from first/above request>&redirect_uri=<call-back url>&scope=openid" 
https://{IDM URL or Asgardeo URL}/oauth2/token

Currently, there is a public client version of the authorization code grant supported by WSO2 for single-page applications and mobile applications, which can be used instead of a client-credential grant. There, we do not need the client secret in the backchannel call. This is a custom grant offered by WSO2 for better security.

Moreover, for better security, you can use PKCE for Single Page Applications or public clients.

Implicit Grant

This grant is fully browser-based; once you copy-paste this sample request, you will receive the token and id-token in the browser response after the authentication. A refresh token is not available.

https://{IDM URL or Asgardeo URL}/oauth2/authorize?response_type=id_token token&client_id=<client-id>&nonce=oidc&redirect_uri=<call-back url>&scope=openid

A sample response to this request will look as follows:

http://testsp/callback#access_token=22f9bf8e-3388-30ca-9740-4f01fc78a25b&id_token=eyJ4NXQiOiJNell4TW1Ga09HWXdNV0kwWldObU5EY3hOR1l3WW1NNFpUQTNNV0kyTkRBelpHUXpOR00wWkdSbE5qSmtPREZrWkRSaU9URmtNV0ZoTXpVMlpHVmxOZyIsImtpZCI6Ik16WXhNbUZrT0dZd01XSTBaV05tTkRjeE5HWXdZbU00WlRBM01XSTJOREF6WkdRek5HTTBaR1JsTmpKa09ERmtaRFJpT1RGa01XRmhNelUyWkdWbE5nX1JTMjU2IiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoiOC1JZVFja3N3RllPTkk0WWt4UkFYdyIsImF1ZCI6IlJSaUpwSklDQm5PZjNQX2NCYm91RUNNUXNrTWEiLCJzdWIiOiJhZG1pbiIsImF6cCI6IlJSaUpwSklDQm5PZjNQX2NCYm91RUNNUXNrTWEiLCJhbXIiOlsiQmFzaWNBdXRoZW50aWNhdG9yIl0sImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImV4cCI6MTYwODIwMzA1NCwiaWF0IjoxNjA4MTk5NDU0LCJub25jZSI6Im9pZGMifQ.r5bFRwyMGoi73SPFvCzzt5oTDpSyMgxvUlK7B9HQEem15TGHMEG3yuKnVxTiZLLRAJx6DHpC6qogSZv4ZrUerSfYTdhGd037sIJdI-KU-nSXoblqerb_189VIVRc1RMBFAzq_ViAk8IbFyR4Sj3gRNJlsj6nBmx7EFbtHRkyfwlAeBlxqUitiKaLimn6zd_Tb2sdAuNAtSkIS9xw1vDMrZhXvcH5IwAVwPGUrsNgVRU3jwR1jdkkVWz04ejQkLpevprpwJe8xy3BYGG9vdwRu7j-A14xtOsUfdODnuINOITW3UB-5FOWZ2CTKdZ8HtrL5LIhMqOQkz8JD-u4ivE2dw&token_type=Bearer&expires_in=3343&session_state=804621bb1c2918cedfdbdcc3a264a69c9ecbf7bd6a81cce1eb2a959cbd122c98._dSvF947coT4ckg8qlreVw

Password Grant

This grant is useful in a scenario where you need to use Basic Authentication behavior. This is the only REST API provided by OAuth2.0 specification similar to username: password authentication. Although many use this for Native clients, it is always recommended to use the native browser when you want to achieve single-sign-on.

curl -u <client id>:<client secret> 
-k -d "grant_type=password&username=<username>&password=<password>&scope=openid" 
-H "Content-Type:application/x-www-form-urlencoded" 
https://{IDM or Asgardeo host URL}/oauth2/token

Client-Credential Grant

This grant is used for public clients like mobile applications and devices to generate application-based access tokens - this is no more considered a secure grant type for public clients. But solutions can be built by using this grant type for the purposes like machine-to-machine access delegation.

curl -u <client id>:<client secret> 
-k -d "grant_type=client_credentials&scope=openid" 
-H "Content-Type:application/x-www-form-urlencoded" 
https://{IDM or Asgardeo host URL}/oauth2/token

Refresh Grant

Refresh grant is used to renew an access token before it expires. With the access token, the refresh token also can be renewed. Authorization code grant, bearer grants, and password grant will provide a refresh token to renew the access token.

curl -k -d "grant_type=refresh_token&refresh_token=<refresh_token>" 
-H "Authorization: Basic <Base64Encoded(Client_Id:Client_Secret)>"
-H "Content-Type: application/x-www-form-urlencoded" 
https://{IDM or Asgardeo host URL}/oauth2/token

Kerberos Grant

Kerberos is a security protocol that has support built into various operating systems and open-source distributions (e.g., Ubuntu, Windows, RedHat, Open Solaris, etc.). Additionally, a majority of browsers support some Kerberos functions as well. A refresh token is available.

curl -v -X POST 
-H "Authorization: Basic <base64 encoded client id:client secret value>"
-k -d "grant_type=kerberos&kerberos_realm=<kerberos realm>&kerberos_token=<kerberos token>" 
-H "Content-Type:application/x-www-form-urlencoded" 
https://{IDM or Asgardeo host URL}/oauth2/token

JWT Bearer Grant

If you have a JWT token or an ID token, you can exchange the JWT token for an access token through this grant.

curl -i -X POST -u <CLIENT_ID>:<Client_SECRET> -k 
-d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<JWT>' 
-H 'Content-Type: application/x-www-form-urlencoded' 
https://{IDM or Asgardeo host URL}/oauth2/token

Other important requests that you need when you work with OAuth2.0 or OpenID Connect

Introspect an Access Token

When an Opaque Access token is received to a server by a client, the server should check whether this access token is valid or not. For that, they use the introspection endpoint of the token issuer.

curl -k -u <USERNAME>:<PASSWORD> 
-H 'Content-Type: application/x-www-form-urlencoded' -X POST 
--data 'token=<ACCESS_TOKEN>' https://{IDM or Asgardeo host URL}/oauth2/introspect

The response will be similar to below:

{"exp":1464161560,"username":"[email protected]","scope":"test1 test2","active":true,"token_type":"Bearer","client_id":"rgfKVdnMQnJSSr_pKFTxj3apiwYa","iat":1464157960}

Revoke Access Token

For security reasons, it is important to revoke access tokens. There is an expiration time for each access token, but through revoke, you can invalidate the token at any time.

curl -X POST — basic -u “<client id>:<client secret>” 
-H “Content-Type: application/x-www-form-urlencoded;charset=UTF-8” 
-k -d “token=<token to revoke>&token_type_hint=access_token” 
https://{IDM or Asgardeo host URL}/oauth2/revoke

Get User info (Id-token information)

When a client uses the OAuth2.0 protocol to get the user’s information, the client exposes an endpoint called the user-info endpoint.

curl -k -H “Authorization: Bearer <Acess_token>” 
https://{IDM or Asgardeo host URL}/oauth2/userinfo?schema=openid

This covers pretty much all the request formats which you need when you try OAuth2.0 and OpenID Connect in WSO2 Identity Server (IAM).

I hope this will help you as a cheat sheet in your developer journey to try out different OAuth2.0 grant types with WSO2 Identity Server or Asgardeo!!!