OIDC to SAML proxy
This project uses a Satosa instance configured with an OIDC frontend, and a SAML backend.
Requirements
- Python 3.8+
- Pipenv
Running the project
Some environment variables need to be set in order to run the project.
They are outlined in the example.env.
You should create a .env file and set those values to the required values.
To run the project locally, you need to install the dependencies via pipenv install.
Afterwards, you can start the service via run.sh.
To run the project in containers, it's enough to simply run docker compose up --build.
Relevant routes
Both the frontend and backend are available under paths starting with their configured names:
The OIDC frontend is available under the path /oidc.
For instance, /oidc/jwks gives information about the key used for signing the JWTs.
Further information can be found under the top-level endpoint /.well-known/openid-configuration.
The SAML backend endpoints are available under the path /saml.
SAML service provider metadata
The SAML service provider metadata can be generated with the following command:
pipenv run satosa-saml-metadata proxy_conf.yml ssl/<tls-key-file> ssl/<tls-cert-file>
If the operation was successful, then the generated should be stored in backend.xml.
Note: We're relying on some environment variables in the configuartion through the !ENV construct.
Thus, the .env file needs to be populated appropriately; pipenv should take care of loading it automatically.
Connecting a Keycloak OIDC client
It is possible and actually relatively simple to add an OIDC client for the SATOSA setup as identity provier in Keycloak.
The above mentioned information endpoint lists the URLs for the relevant OIDC endpoints:
- Authorization URL
- Token URL
- User info URL
Configuring the JWKS endpoint also enables validation of the JWT signatures. Also, validation of the issuer is recommended.
Further, the following configuration is required:
- Client ID and secret: Values as registered in the SATOSA setup
- Client authentication:
Client secret sent as basic auth - Scopes:
openid profile email extras
The extras scope includes affiliation information, if present.
Configuring OIDC clients
Dynamic registration of OIDC clients is disabled per configuration.
Instead, clients for the OIDC frontend should be configured via oidc-clients.json.
An example configuration can be found in the file oidc-clients.json.example.
SSL/TLS keys
Our Satosa setup needs three sets of key files for its operation:
- The usual key and certificate for enabling HTTPS on Gunicorn
- A key and certificate for SAML signatures
- A public/private key pair (but no certificate) for signing OIDC JWTs
Of course, the HTTPS certificate has to be signed by a trusted certificate authority and valid.
The certificate used for SAML signatures doesn't have to be signed by any trusted certificate authority. A self-signed one is absolutely fine, and its expiration date also doesn't matter. It only matters that you're the only one who is able to produce signatures that can be verified by the other SAML participants. The certificate is exposed publicly as part of the SAML metadata. There's no need to update the certificate or private key, just keep the latter safe.
With the public/private key for signing the OIDC JWTs it's similar. There's no need for a certificate here, just the private key file.
Generating keys and certificates
Generate a new private key:
certtool --generate-privkey --outfile test.key
Generate a self-signed certificate with a private key:
certtool --generate-self-signed --load-privkey test.key --outfile test.crt
Viewing info about keys and files
View info about the private key from a private key file:
certtool --key-info --load-privkey test.key
View info about the public key from a private key file:
certtool --pubkey-info --load-privkey test.key
View info about a certificate from a certificate file:
certtool --certificate-info --infile test.crt
Further reading about SAML and ACOnet
Here is a collection of links for further resources about SAML and the ACOnet federation: