Authentication API

Below is a guide to using Keycloak's Authentication API for common tasks such as obtaining tokens, refreshing tokens, and validating tokens.

1. Set Up TideCloak

Before using the API, ensure you have a TideCloak server running and configured:

• Create a realm.
• Create a client (e.g., my-client) with the appropriate settings (e.g., confidential access type).
• Create users and roles.

2. TideCloak Authentication API Endpoints

TideCloak provides a RESTful API for authentication. The base URL for the API is typically:

http://`<TideCloak-server>`/auth/realms/`<realm>`/protocol/openid-connect

Common Endpoints

• Token Endpoint : /token (for obtaining and refreshing tokens)
• User Info Endpoint : /userinfo (for retrieving user information)
• Logout Endpoint : /logout (for logging out)
• Introspection Endpoint : /token/introspect (for validating tokens)

---

3. Obtain an Access Token

To authenticate a user, you need to obtain an access token using the /token endpoint.

Request

• Method : POST
• URL : http://<TideCloak-server>/auth/realms/<realm>/protocol/openid-connect/token
• Headers :
• Content-Type: application/x-www-form-urlencoded
• Body (form-urlencoded):
• grant_type: password (for password grant)
• client_id: Your client ID (e.g., my-client)
• client_secret: Your client secret (if using confidential client)
• username: User's username
• password: User's password

Example

curl -X POST \
  http://localhost:8080/auth/realms/my-realm/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-client" \
  -d "client_secret=<client-secret>" \
  -d "username=user1" \
  -d "password=password" \
  -d "grant_type=password"

Response

{
  "access_token": "<access-token>",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "<refresh-token>",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "<session-state>",
  "scope": "profile email"
}

---

4. Refresh an Access Token

If the access token expires, you can use the refresh token to obtain a new access token.

Request

• Method : POST
• URL : http://<TideCloak-server>/auth/realms/<realm>/protocol/openid-connect/token
• Headers :
• Content-Type: application/x-www-form-urlencoded
• Body (form-urlencoded):
• grant_type: refresh_token
• client_id: Your client ID
• client_secret: Your client secret
• refresh_token: The refresh token from the previous response

Example

curl -X POST \
  http://localhost:8080/auth/realms/my-realm/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-client" \
  -d "client_secret=<client-secret>" \
  -d "refresh_token=<refresh-token>" \
  -d "grant_type=refresh_token"

Response

The response will be similar to the initial token response, with a new access token and refresh token.

---

5. Validate a Token

To validate an access token, use the /token/introspect endpoint.

Request

• Method : POST
• URL : http://<TideCloak-server>/auth/realms/<realm>/protocol/openid-connect/token/introspect
• Headers :
• Content-Type: application/x-www-form-urlencoded
• Body (form-urlencoded):
• client_id: Your client ID
• client_secret: Your client secret
• token: The access token to validate

Example

curl -X POST \
  http://localhost:8080/auth/realms/my-realm/protocol/openid-connect/token/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-client" \
  -d "client_secret=<client-secret>" \
  -d "token=<access-token>"

Response

{
  "active": true,
  "exp": 1672502400,
  "iat": 1672498800,
  "sub": "<user-id>",
  "username": "user1",
  "email": "user1@example.com"
}

---

6. Logout

To log out a user and invalidate their session, use the /logout endpoint.

Request

• Method : POST
• URL : http://<TideCloak-server>/auth/realms/<realm>/protocol/openid-connect/logout
• Headers :
• Content-Type: application/x-www-form-urlencoded
• Body (form-urlencoded):
• client_id: Your client ID
• client_secret: Your client secret
• refresh_token: The refresh token to invalidate

Example

curl -X POST \
  http://localhost:8080/auth/realms/my-realm/protocol/openid-connect/logout \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-client" \
  -d "client_secret=<client-secret>" \
  -d "refresh_token=<refresh-token>"

Response

A successful logout will return a 204 No Content response.

---

7. Retrieve User Information

To retrieve user information, use the /userinfo endpoint.

Request

• Method : GET
• URL : http://<TideCloak-server>/auth/realms/<realm>/protocol/openid-connect/userinfo
• Headers :
• Authorization: Bearer <access-token>

Example

curl -X GET \
  http://localhost:8080/auth/realms/my-realm/protocol/openid-connect/userinfo \
  -H "Authorization: Bearer <access-token>"

Response

{
  "sub": "<user-id>",
  "email_verified": true,
  "name": "User One",
  "preferred_username": "user1",
  "given_name": "User",
  "family_name": "One",
  "email": "user1@example.com"
}

---

8. Error Handling

TideCloak returns standard HTTP status codes and error messages. For example:

• 400 Bad Request: Invalid request parameters.
• 401 Unauthorized: Invalid credentials or token.
• 403 Forbidden: Insufficient permissions.

Error responses typically include a JSON body with details:

{
  "error": "invalid_grant",
  "error_description": "Invalid user credentials"
}