Direct Access Grants
Keycloak allows you to make direct REST invocations to obtain an access token.
(See Resource Owner Password Credentials Grant
from OAuth 2.0 spec). To use it, Direct Access Grants must be allowed by your realm. This is a configuration switch
in the admin console under Settings->General, specifically the "Direct Grant API" switch. You must also have
registered a valid OAuth Client or Application to use as the "client_id" for this grant request.
It is highly recommended that you do not use Direct Access Grants to write your own login pages for your application.
You will lose a lot of features that Keycloak has if you do this. Specifically all the account management, remember me,
lost password, account reset features of Keycloak. Instead, if you want to tailor the look and feel of Keycloak login
pages, you should create your own theme.
It is even highly recommended that you use the browser to log in for native mobile applications! Android
and iPhone applications allow you to redirect to and from the browser. You can use this to redirect the user
from your native mobile app to the web browser to perform login, then the browser will redirect back to your
native application.
The REST URL to invoke on is /{keycloak-root}/realms/{realm-name}/tokens/grants/access.
Invoking on this URL is a POST request and requires you to post the username and credentials of the user you want
an access token for. You must also pass along the "client_id" of the application or oauth client you are creating
an access token for. This "client_id" is the application or oauth client name (not it's id!). Depending on
whether your application/oauth client is "public" or "confidential", you may also have to pass along
it's client secret as well.
For public applications or oauth client's, the POST invocation requires form parameters that contain the username,
credentials, and client_id of your application. For example:
The response would be this standard JSON document from the OAuth 2.0 specification.
For confidential applications or oauth client's, you must create a Basic Auth Authorization
header that contains the client_id and client secret. And pass in the form parameters for username and for
each user credential. For example:
Here's a Java example using Apache HTTP Client and some Keycloak utility classes.:
formparams = new ArrayList ();
formparams.add(new BasicNameValuePair("username", "bburke"));
formparams.add(new BasicNameValuePair("password", "password"));
if (isPublic()) { // if client is public access type
formparams.add(new BasicNameValuePair(OAuth2Constants.CLIENT_ID, "customer-portal"));
formparams.add(new BasicNameValuePair(OAuth2Constants.GRANT_TYPE, "password"));
} else {
String authorization = BasicAuthHelper.createHeader("customer-portal", "secret-secret-secret");
post.setHeader("Authorization", authorization);
}
UrlEncodedFormEntity form = new UrlEncodedFormEntity(formparams, "UTF-8");
post.setEntity(form);
HttpResponse response = client.execute(post);
int status = response.getStatusLine().getStatusCode();
HttpEntity entity = response.getEntity();
if (status != 200) {
throw new IOException("Bad status: " + status);
}
if (entity == null) {
throw new IOException("No Entity");
}
InputStream is = entity.getContent();
try {
AccessTokenResponse tokenResponse = JsonSerialization.readValue(is, AccessTokenResponse.class);
} finally {
try {
is.close();
} catch (IOException ignored) { }
}
} finally {
client.getConnectionManager().shutdown();
}
]]>
Once you have the access token string, you can use it in REST HTTP bearer token authorized requests, i.e
GET /my/rest/api
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
To logout you must use the refresh token contained in the AccessTokenResponse object.
formparams = new ArrayList();
if (isPublic()) { // if client is public access type
formparams.add(new BasicNameValuePair(OAuth2Constants.CLIENT_ID, "customer-portal"));
} else {
String authorization = BasicAuthHelper.createHeader("customer-portal", "secret-secret-secret");
post.setHeader("Authorization", authorization);
}
formparams.add(new BasicNameValuePair(OAuth2Constants.REFRESH_TOKEN, tokenResponse.getRefreshToken()));
HttpResponse response = null;
URI logoutUri = KeycloakUriBuilder.fromUri(getBaseUrl(request) + "/auth")
.path(ServiceUrlConstants.TOKEN_SERVICE_LOGOUT_PATH)
.build("demo");
HttpPost post = new HttpPost(logoutUri);
UrlEncodedFormEntity form = new UrlEncodedFormEntity(formparams, "UTF-8");
post.setEntity(form);
response = client.execute(post);
int status = response.getStatusLine().getStatusCode();
HttpEntity entity = response.getEntity();
if (status != 204) {
error(status, entity);
}
if (entity == null) {
return;
}
InputStream is = entity.getContent();
if (is != null) is.close();
]]>