This repository provides the proof-of-concept implementation of the end-to-end authentication for an OpenID Connect OpenID Provider server.
The provided implementation is written in Go and implements a REST endpoint for the Identity Certification Token UserInfo endpoint. Using a reverse proxy in front, it can be mounted to any OpenID Provider implementation.
Warning: Keep in mind that this is the implementation of a research project! We do not guarantee a secure implementation! Do not use this in production!!!
This section provides an introduction to the architecture and the configuration of the Identity Certification Token Endpoint.
The following figure shows the overall architecture how to use the provided Identity Certification Token (ICT) Endpoint with any OpenID Provider implementation.
+---------+ +----------+ +----------+
/* | | * | OpenID | | User |
-----------------------> | |--------------->| Provider | <-------> | Database |
| | +----------+ +----------+
| | ^
| Reverse | | /realms/ict/protocol/openid-
| Proxy | | connect/userinfo
/realms/ict/protocol/ | | +----------+
openid-connect/ict | | / | ICT |
-----------------------> | |--------------->| Endpoint |
+---------+ +----------+
The Docker Compose composition provided here uses the following implementations:
- Reverse Proxy: Traefik Proxy
- OpenID Provider: Keycloak
- User Database: PostgreSQL
- Identity Certification Token (ICT) Endpoint: An HTTP endpoint written in GO
This section describes the configuration parameters of the ICT Endpoint.
They are applied by injecting them as environment variables to the running application.
This can be done by defining the variables in the Docker container or by placing an .env
file in the execution directory.
Absolute or relative file path to the OpenID Provider's private key file in PEM format.
Example:
KEY_FILE="/path/to/private_key.pem"
Setting this variable is required.
The ID of the OpenID Provider's Public Key provided in the jwks_uri
endpoint.
Example 1:
KID="rojPQoDRx_DD-DFs7y45wDLl5T8b9VmX6iQapIK6cRE"
Example 2:
KID=1
Setting this variable is required.
Signing algorithm for Identity Certification Token signatures.
Allowed values are:
RS256
for RSASSA-PKCS1-v1_5 using SHA-256RS384
for RSASSA-PKCS1-v1_5 using SHA-384RS512
for RSASSA-PKCS1-v1_5 using SHA-512ES256
for ECDSA using P-256 and SHA-256 (recommended)ES384
for ECDSA using P-384 and SHA-384ES512
for ECDSA using P-521 and SHA-512EdDSA
for Eduard Digital Signing Algorithm using Ed25519 curve
Default Value: ES256
.
Example:
ALG="ES256"
Absolute URI to the OpenID Provider's Userinfo Endpoint.
This URI is used by the ICT Endpoint to request the claims of the Identity Certification Token from the OpenID Provider. Make sure that the running ICT Endpoint can access the OpenID Provider's Userinfo Endpoint via this URI!
Example 1:
USERINFO="https://openid-provider.sample.org/userinfo"
Example 2 (Keycloak):
USERINFO="http://localhost:8080/realms/ict/protocol/openid-connect/userinfo"
Setting this variable is required.
Absolute URI to the OpenID Provider's Token Introspection Endpoint described in RFC 7662.
This URI is provided on the Discovery Endpoint as attribute introspection_endpoint
.
Make sure that the running ICT Endpoint can access the OpenID Provider's Token Introspection Endpoint via this URI!
Example 1:
TOKEN_INTROSPECTION="https://openid-provider.sample.org/introspect"
Example 2 (Keycloak):
TOKEN_INTROSPECTION="http://localhost:8080/realms/ict/protocol/openid-connect/token/introspect"
Setting this variable is required.
The hostname in HTTP Host Header when requesting the Token Introspection Endpoint.
If not provided, the hostname from the TOKEN_INTROSPECTION
URL will be used.
Example:
TOKEN_INTROSPECTION_HOST="openid-provider.sample.org
The HTTP Authorization Header required for the Token Introspection Endpoint. Typically a HTTP Basic Authentication Header using the ICT Endpoint's Client Credentials.
Example:
INTROSPECTION_CREDENTIALS="Basic aWN0X2VuZHBvaW50OlMzY3JldCE="
For Client ID ict_endpoint
and Client Secret S3cret!
Setting this variable is required, except the OpenID Provider does not requires any authorization for the Token Introspection Endpoint (not recommended).
Prefix of scopes which indicate the granted end-to-end authentication context.
Default Value: e2e_ctx_
.
Example:
CONTEXT_PREFIX="ctx_"
The scope ctx_email
will authorize the End-User for the email
context.
The Identity Certification Token's Issuer.
This is the value of the iss
claim of the issued Identity Certification Token.
Typically, this is the public URI of the OpenID Provider where .well-known/openid-configuration
is added to request the OpenID configuration.
Example 1:
ISSUER="https://accounts.sample.org/"
Example 2:
ISSUER="http://localhost:8080/realms/ict"
Setting this variable is required.
The Identity Certification Token's default validity period in seconds.
Default Value: 3600
(1 hour).
Example:
DEFAULT_TOKEN_PERIOD=3600
The Identity Certification Token's maximum validity period in seconds. If the requested token period is longer than this value, this value is used.
Default Value: 2592000
(30 days).
Example:
MAX_TOKEN_PERIOD=2592000
The Port where the endpoint is running on.
Default Value: 8080
.
Example:
PORT=8080
The SQLite database file to store used nonce values in.
Default Value (standalone): ./db.sqlite
Default Value (Docker image): /config/db.sqlite
Example:
DB_SQLITE_FILE="/config/db.sqlite"
The REST API is described in the OpenAPI format provided here.
To setup a test environment locally, refer to the manual here.
To play around with the API, check out the testing manual here.
To improve the security of a deployment, check out the security manual here.