Skip to content

Latest commit

 

History

History
189 lines (156 loc) · 12.4 KB

README.md

File metadata and controls

189 lines (156 loc) · 12.4 KB
Raw

mod-login-keycloak

Copyright (C) 2023-2023 The Open Library Foundation

This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.

Table of contents

Introduction

mod-login-keycloak provides following functionality:

  • Uses keycloak token to authenticate in the okapi gateway.
  • Application health and availability monitoring.

Environment Variables

Name Default value Required Description
KC_URL - true Keycloak URL
KC_LOGIN_CLIENT_SUFFIX login-application false Keycloak client suffix
DB_HOST localhost false Postgres hostname
DB_PORT 5432 false Postgres port
DB_USERNAME postgres false Postgres username
DB_PASSWORD postgres false Postgres username password
DB_DATABASE postgres false Postgres database name
KC_CONFIG_STORE_TYPE ephemeral false Secure storage type
ENV folio false Environment name
KC_CONFIG_TTL 3600s false Client credentials expiration timeout
KC_ADMIN_TOKEN_TTL 410s false Admin token cache ttl
KC_ADMIN_PASSWORD keycloak_system_admin true Keycloak admin password
X_OKAPI_TOKEN_HEADER_ENABLED false false Enable x-okapi-token header for login similar API methods
LOGIN_COOKIE_SAMESITE None false Value for the SameSite attribute in a cookie header
login.cookie.samesite None false Alias for LOGIN_COOKIE_SAMESITE

Secure storage environment variables

AWS-SSM

Required when SECRET_STORE_TYPE=AWS_SSM

Name Default value Description
SECRET_STORE_AWS_SSM_REGION - The AWS region to pass to the AWS SSM Client Builder. If not set, the AWS Default Region Provider Chain is used to determine which region to use.
SECRET_STORE_AWS_SSM_USE_IAM true If true, will rely on the current IAM role for authorization instead of explicitly providing AWS credentials (access_key/secret_key)
SECRET_STORE_AWS_SSM_ECS_CREDENTIALS_ENDPOINT - The HTTP endpoint to use for retrieving AWS credentials. This is ignored if useIAM is true
SECRET_STORE_AWS_SSM_ECS_CREDENTIALS_PATH - The path component of the credentials endpoint URI. This value is appended to the credentials endpoint to form the URI from which credentials can be obtained.

Vault

Required when SECRET_STORE_TYPE=VAULT

Name Default value Description
SECRET_STORE_VAULT_TOKEN - token for accessing vault, may be a root token
SECRET_STORE_VAULT_ADDRESS - the address of your vault
SECRET_STORE_VAULT_ENABLE_SSL false whether or not to use SSL
SECRET_STORE_VAULT_PEM_FILE_PATH - the path to an X.509 certificate in unencrypted PEM format, using UTF-8 encoding
SECRET_STORE_VAULT_KEYSTORE_PASSWORD - the password used to access the JKS keystore (optional)
SECRET_STORE_VAULT_KEYSTORE_FILE_PATH - the path to a JKS keystore file containing a client cert and private key
SECRET_STORE_VAULT_TRUSTSTORE_FILE_PATH - the path to a JKS truststore file containing Vault server certs that can be trusted

Keycloak environment variables

Keycloak all configuration properties: https://www.keycloak.org/server/all-config

Name Description
KC_HOSTNAME Keycloak hostname, will be added to returned endpoints, for example for openid-configuration
KC_ADMIN Initial admin username
KC_ADMIN_PASSWORD Initial admin password
KC_DB Database type
KC_DB_URL_DATABASE Sets the database name of the default JDBC URL of the chosen vendor. If the DB_URL option is set, this option is ignored.
KC_DB_URL_HOST Sets the hostname of the default JDBC URL of the chosen vendor. If the DB_URL option is set, this option is ignored.
KC_DB_URL_PORT Sets the port of the default JDBC URL of the chosen vendor. If the DB_URL option is set, this option is ignored.
KC_DB_USERNAME Database Username
KC_DB_PASSWORD Database Password
KC_PROXY The proxy address forwarding mode if the server is behind a reverse proxy. Possible values are: edge, reencrypt, passthrough. https://www.keycloak.org/server/reverseproxy
KC_HOSTNAME_STRICT Disables dynamically resolving the hostname from request headers. Should always be set to true in production, unless proxy verifies the Host header.
KC_HOSTNAME_PORT The port used by the proxy when exposing the hostname. Set this option if the proxy uses a port other than the default HTTP and HTTPS ports. Defaults to -1.
KC_CLIENT_TLS_ENABLED Enables TLS for keycloak clients.
KC_CLIENT_TLS_TRUSTSTORE_PATH Truststore file path for keycloak clients.
KC_CLIENT_TLS_TRUSTSTORE_PASSWORD Truststore password for keycloak clients.
KC_CLIENT_TLS_TRUSTSTORE_TYPE Truststore file type for keycloak clients.

Kafka environment variables

Kafka all configuration properties: https://kafka.apache.org/documentation/#configuration

Name Description
KAFKA_SSL_KEYSTORE_PASSWORD Kafka keystore password
KAFKA_SSL_KEYSTORE_LOCATION Kafka keystore location
KAFKA_SSL_TRUSTSTORE_PASSWORD Kafka truststore password
KAFKA_SSL_TRUSTSTORE_LOCATION Kafka truststore location

Loading of client IDs/secrets

The module pulls client_secret for client_id from AWS Parameter store, Vault or other reliable secret storages when they are required for login. The credentials are cached for 3600s.

Interaction with keycloak

Authenticate with Keycloak (using user's credentials) and get back an access token and refresh token

curl -XPOST \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "username=$username" \
--data-urlencode "password=$password" \
--data-urlencode "client_id=$clientId" \
--data-urlencode "client_secret=$clientSecret" \
--data-urlencode "grant_type=password" \
--data-urlencode "scopes=openid profile email" \
"$keycloakUrl/realms/$tenantId/protocol/openid-connect/token"

Get User Info

curl -XGET \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer $acessToken" \
"$keycloakUrl/realms/$tenantId/protocol/openid-connect/userinfo"

Introspect Token

curl -XPOST \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "token=$accessToken" \
--data-urlencode "client_id=$clientId" \
--data-urlencode "client_secret=$clientSecret" \
"$keycloakUrl/realms/$tenantId/protocol/openid-connect/token/introspect"

Refresh token

curl -XPOST \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "refresh_token=$refreshToken" \
--data-urlencode "client_id=$clientId" \
--data-urlencode "client_secret=$clientSecret" \
--data-urlencode "grant_type=refresh_token" \
"$keycloakUrl/realms/$tenantId/protocol/openid-connect/token"

Logout

curl -XPOST \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "refreshToken=$refreshToken" \
--data-urlencode "client_id=$clientId" \
--data-urlencode "client_secret=$clientSecret" \
"$keycloakUrl/realms/$tenantId/protocol/openid-connect/logout"

Reset password

curl -XPUT \
-H "Content-Type: application/json" \
-H "Authorization: $KEYCLOAK_TOKEN" \
--data-raw '{
    "temporary": false,
    "type": "password",
    "value": "demouser"
}'
"$keycloakUrl/admin/realms/$tenantId/users/{userId}/reset-password"

Get Credentials

curl -XGET \
-H "Content-Type: application/json" \
-H "Authorization: $KEYCLOAK_TOKEN" \
"$keycloakUrl/admin/realms/$tenantId/users/{userId}/credentials"

Delete Credentials

curl -XDELETE \
-H "Content-Type: application/json" \
-H "Authorization: $KEYCLOAK_TOKEN" \
"$keycloakUrl/admin/realms/$tenantId/users/{userId}/credentials/{credentialId}"