Create Auth Microservice for Keycloak Token Operations #1

New issue

Closed

opened 2025-04-22 21:31:42 +00:00 by abed.alrahman · 2 comments

abed.alrahman commented

2025-04-22 21:31:42 +00:00

Member

Ref epic: #13

Goal: Develop a new microservice (auth-service) to provide simple REST endpoints for handling Keycloak authentication tasks: user login (username/password), token verification, and user logout.

Background:
While Keycloak and Traefik handle UI logins and request authentication, we need a way for applications or scripts to programmatically log in users and validate tokens without going through complex browser-based OAuth2 flows. This auth-service will act as a simplified interface to Keycloak for these specific tasks.

Requirements / What needs to be done:

Choose Technology: Decide on a language/framework for the microservice (e.g.,  Java/Kotlin with Spring Boot). 
Design API Endpoints: Define and implement the following REST endpoints:
    POST /login
        Purpose: Authenticate a user with username and password to get tokens.
        Request Body: {"username": "user", "password": "password"}
        Action: Use Keycloak's token endpoint with the Resource Owner Password Credentials (ROPC) grant type.
            Security Note: ROPC should only be enabled in Keycloak for trusted clients, as it handles user passwords directly. This service acts as that trusted client.
        Success Response (200 OK): {"access_token": "...", "expires_in": 300, "refresh_expires_in": 1800, "refresh_token": "...", "token_type": "Bearer", ...} (Return standard Keycloak token response).
        Error Responses: 400 Bad Request (missing fields), 401 Unauthorized (invalid credentials).
    POST /verify
        Purpose: Validate an access token and retrieve user information.
        Request Header: Authorization: Bearer <access_token>
        Action: Use Keycloak's token introspection endpoint or the userinfo endpoint.
        Success Response (200 OK): {"active": true, "username": "user", "email": "...", "groups": ["group1", ...], "realm_access": {"roles": [...]}, ...} (Return relevant user metadata from Keycloak).
        Error Responses: 401 Unauthorized (invalid/expired token).
    POST /logout
        Purpose: Log out the user by invalidating their session/tokens.
        Request Body: {"refresh_token": "..."} (Using the refresh token is standard for ending the session).
        Action: Use Keycloak's logout endpoint or token revocation endpoint with the provided refresh token.
        Success Response (204 No Content): No body content needed.
        Error Responses: 400 Bad Request (missing refresh token), 401 Unauthorized (invalid refresh token).
Keycloak Integration:
    Configure the service to connect to Keycloak using environment variables or configuration files:
        Keycloak base URL (e.g., http://keycloak.dev.localhost/)
        Realm name (e.g., myrealm)
        Client ID for this auth-service (needs to be created in Keycloak, likely confidential, ROPC grant enabled).
        Client Secret (if using a confidential client).
    Use a robust OAuth2/OIDC library for the chosen language to handle interactions.

Ref epic: [#13](https://git.cleverthis.com/clevermicro/user-management/issues/13) Goal: Develop a new microservice (auth-service) to provide simple REST endpoints for handling Keycloak authentication tasks: user login (username/password), token verification, and user logout. Background: While Keycloak and Traefik handle UI logins and request authentication, we need a way for applications or scripts to programmatically log in users and validate tokens without going through complex browser-based OAuth2 flows. This auth-service will act as a simplified interface to Keycloak for these specific tasks. Requirements / What needs to be done: Choose Technology: Decide on a language/framework for the microservice (e.g., Java/Kotlin with Spring Boot). Design API Endpoints: Define and implement the following REST endpoints: POST /login Purpose: Authenticate a user with username and password to get tokens. Request Body: {"username": "user", "password": "password"} Action: Use Keycloak's token endpoint with the Resource Owner Password Credentials (ROPC) grant type. Security Note: ROPC should only be enabled in Keycloak for trusted clients, as it handles user passwords directly. This service acts as that trusted client. Success Response (200 OK): {"access_token": "...", "expires_in": 300, "refresh_expires_in": 1800, "refresh_token": "...", "token_type": "Bearer", ...} (Return standard Keycloak token response). Error Responses: 400 Bad Request (missing fields), 401 Unauthorized (invalid credentials). POST /verify Purpose: Validate an access token and retrieve user information. Request Header: Authorization: Bearer <access_token> Action: Use Keycloak's token introspection endpoint or the userinfo endpoint. Success Response (200 OK): {"active": true, "username": "user", "email": "...", "groups": ["group1", ...], "realm_access": {"roles": [...]}, ...} (Return relevant user metadata from Keycloak). Error Responses: 401 Unauthorized (invalid/expired token). POST /logout Purpose: Log out the user by invalidating their session/tokens. Request Body: {"refresh_token": "..."} (Using the refresh token is standard for ending the session). Action: Use Keycloak's logout endpoint or token revocation endpoint with the provided refresh token. Success Response (204 No Content): No body content needed. Error Responses: 400 Bad Request (missing refresh token), 401 Unauthorized (invalid refresh token). Keycloak Integration: Configure the service to connect to Keycloak using environment variables or configuration files: Keycloak base URL (e.g., http://keycloak.dev.localhost/) Realm name (e.g., myrealm) Client ID for this auth-service (needs to be created in Keycloak, likely confidential, ROPC grant enabled). Client Secret (if using a confidential client). Use a robust OAuth2/OIDC library for the chosen language to handle interactions.

abed.alrahman added the

labels

2025-04-22 21:31:42 +00:00

abed.alrahman added reference feat#1_creating_service

2025-04-27 23:15:03 +00:00

stanislav.hejny added the

Type

Task

label

2025-04-29 10:31:16 +00:00

stanislav.hejny commented

2025-04-29 10:33:02 +00:00

Member

depends on / is blocked by 'have independent keycloak instance deployed' in CleverThis company context, as a DEVELOPMENT env instance (identity-management project task)

stanislav.hejny added the

Rows
Columns