Keycloak: Requesting Token with Password Grant

In this tutorial, you will learn how to use a Password Grant OAuth 2 authorization flow to request an Access Token and a Refresh token from the Keycloak server by sending HTTP Post request to a /token web service endpoint.

The Password Grant flow should only be used if your application does not support redirects. Otherwise, if your application is a Web application or a mobile application and does support redirects, it is recommended to use an Authorization Code grant flow. If your application is a secure mobile application and a user has an absolute trust for this mobile application and is ready to provide it with their username and password, then a Password Grant flow can be used. Although, the latest OAuth 2.0 Security Best Current Practice disallows the password grant entirely.

The password grant can also be useful when you need to migrate existing clients by converting their stored credentials to an OAuth access token.

I assume that you already have a Keycloak server running and a user created. Otherwise, please follow these two tutorials first:

1. Keycloak: Starting a Standalone Server,
2. Keycloak: Creating a New User.

Getting Access Token with Password Grant Type

The following HTTP Post request can be used to request an access token and a refresh token using user’s(Resource Owner) password credentials. Before sending this request make sure the Keycloak server is running and the user’s credentials are correct.

curl --location --request POST 'http://localhost:8080/auth/realms/appsdeveloperblog/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'password=USER-PASSWORD' \
--data-urlencode 'username=USER-NAME' \
--data-urlencode 'client_id=photo-app-client' \
--data-urlencode 'grant_type=password'

Where:

• localhost:8080 – is a host and a port number on which the Keycloak server is running,
• appsdeveloperblog – is a Keycloak Realm,
• photo-app-client – is an OAuth client registered with Keycloak authorization server,
• The USER-PASSWORD and the USER-NAME – are the Resource Owner(user) login credentials,
• password –  is a password grant.  The Grant Type is a way to exchange a user’s credentials for an access token.

In case of a successful request, you should see a similar JSON in a Response Body:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICItNUlsX2I0cUktdWFvaEI3d244UHY3WEM2UEktU3BNbmZCRnlJZUx6QTJNIn0.eyJleHAiOjE1OTIyNDg2OTAsImlhdCI6MTU5MjI0ODM5MCwianRpIjoiNTBmZmE5OGYtYjBmMS00MmY1LTljMjEtOTM3MDlkMTE3YjNiIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL2FwcHNkZXZlbG9wZXJibG9nIiwiYXVkIjpbInJlYWxtLW1hbmFnZW1lbnQiLCJhY2NvdW50Il0sInN1YiI6IjFkZGUzZmMzLWM2ZGItNDlmYi05YjNkLTc5NjRjNWMwNjg3YSIsInR5cCI6IkJlYXJlciIsImF6cCI6InBob3RvLWFwcC1jbGllbnQiLCJzZXNzaW9uX3N0YXRlIjoiNmYxOGNlZjUtZTI5OS00ZWMyLTgwMjAtODhkMmQ5N2EzZDNiIiwiYWNyIjoiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJVc2VyIiwib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7InJlYWxtLW1hbmFnZW1lbnQiOnsicm9sZXMiOlsidmlldy1yZWFsbSIsInZpZXctaWRlbnRpdHktcHJvdmlkZXJzIiwibWFuYWdlLWlkZW50aXR5LXByb3ZpZGVycyIsImltcGVyc29uYXRpb24iLCJyZWFsbS1hZG1pbiIsImNyZWF0ZS1jbGllbnQiLCJtYW5hZ2UtdXNlcnMiLCJxdWVyeS1yZWFsbXMiLCJ2aWV3LWF1dGhvcml6YXRpb24iLCJxdWVyeS1jbGllbnRzIiwicXVlcnktdXNlcnMiLCJtYW5hZ2UtZXZlbnRzIiwibWFuYWdlLXJlYWxtIiwidmlldy1ldmVudHMiLCJ2aWV3LXVzZXJzIiwidmlldy1jbGllbnRzIiwibWFuYWdlLWF1dGhvcml6YXRpb24iLCJtYW5hZ2UtY2xpZW50cyIsInF1ZXJ5LWdyb3VwcyJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJlbWFpbCBwcm9maWxlIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJnZXkifQ.gauVxQ-xKBQO51JdgrUnTSjZt6pKiN1pYzWEmNYXH45pj4sFSt9249mOn6J9X6OpJxkl5H5o2b2PPX9X7ZnLYz4i-mXHuYpNhVlmpbee2xH8i3_RmjcBSJebyjs11T8QrAj41mADNYZXLi_mW7Uu7ecSrUiBHoioaMBJnX7CUPN67Q1ctviCkNqbkrPsZyYFaky0en-smBGMMVmLaIS6xksBnxAZBLcalw4IkU7YVFynT-qGUhwGiGrkcTZwSLCowCZcBK3mAH_otdNqiTlGcGgAdqn0ea092WS0EdzR2bAMddCXM7FsD_HzooouxdvPgMuoxaHPp9rClh7dlX7fNw",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJlYWQyMDZmOS05MzczLTQ1OTAtOGQ4OC03YWNkYmZjYTU5MmMifQ.eyJleHAiOjE1OTIyNTAxOTAsImlhdCI6MTU5MjI0ODM5MCwianRpIjoiNzJlNTI1YmMtNDIwMy00MDhiLThhYzAtYzk2ZGNiYTFhOTI2IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL2FwcHNkZXZlbG9wZXJibG9nIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL2FwcHNkZXZlbG9wZXJibG9nIiwic3ViIjoiMWRkZTNmYzMtYzZkYi00OWZiLTliM2QtNzk2NGM1YzA2ODdhIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6InBob3RvLWFwcC1jbGllbnQiLCJzZXNzaW9uX3N0YXRlIjoiNmYxOGNlZjUtZTI5OS00ZWMyLTgwMjAtODhkMmQ5N2EzZDNiIiwic2NvcGUiOiJlbWFpbCBwcm9maWxlIn0.c5JZg9Y-a1etKmF3uRcnbKKIeAIDe72cz1tPe5IzpRo",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "6f18cef5-e299-4ec2-8020-88d2d97a3d3b",
    "scope": "email profile"
}

You might have noticed that, although the above request does not specify a scope request parameter, the response JSON document does contain two scope values returned: “email” and “profile”. These are just the Default Client Scopes registered with at the authorization server. Your OAuth client might have different scopes configured.

I hope this short tutorial was helpful to you. Have a look at other tutorials about OAuth and the Keycloak authorization server on this web site. You might find more interesting tutorials to read.