Smallstep Certificate Manager Single Sign-on Certificates

User certificates enable mutual TLS authentication between humans and APIs, VPNs, databases, and more. Add single sign-on to to the mix, and you get a layer of strong authentication from your existing identity provider (IdP), using tools familiar to your team. It works for designated admininistrators, too: Admins can get certificates with any name or SAN, simplifying human approval workflows for security teams.

Certificate Manager supports any OAuth OpenID connect IdP for single sign-on, including Google, Okta, Azure Active Directory, and Keycloak.

Connect your identity provider to Certificate Manager in a few steps

  1. Create an OIDC application integration with your IdP
  2. Add an OIDC provisioner to your Smallstep Authority
  3. Enable self-service single sign-on certificates
  4. Add a Provisioner Admin who can issue custom certificates (optional)

Requirements

  • This documentation assumes you have initialized and started up a Certificate Manager Authority using the steps in Getting Started.
  • Administrator privileges on your Smallstep Authority
  • IDP privileges capable of creating a new OIDC application integration and assigning users to the integration.

Step 1 - Create an OIDC application integration with your IdP.

OpenID Connect is an extension to OAuth 2.0 that adds an identity layer. Providers that support OIDC can issue identity tokens ("ID tokens") to OAuth clients. These are JSON Web Tokens (JWTs) containing user identity information (eg. full name, username, email address). Like certificates, OIDC tokens have a validity period and are cryptographically signed by a trust authority (the IdP).

First, create an OIDC application in your IdP. Be sure to set the following values:

  • Login Redirect URI: Specify http://127.0.0.1
  • Use Client Authentication: Note the Client ID and Client Secret, these values will be used when creating an OIDC provisioner in Certificate Manager
  • Look in your application settings or documentation for the OIDC configuration endpoint URL. It will end in /.well-known/openid-configuration.

Step 2 - Add an OIDC provisioner to your Authority.

The OIDC provisioner in Certificate Manager can be configured to trust and accept an OAuth provider's ID tokens for authentication. The issued certificate will use the subject (sub) claim from the identity token as its subject by default. The value of the token's email claim is also included as an email SAN in the certificate. Use the following command as a template for adding an OIDC provisioner.

$ step ca provisioner add [NAME] --type OIDC \ --client-id [YOUR CLIENT ID] \ --client-secret [YOUR CLIENT SECRET] \ --configuration-endpoint [YOUR IdP CONFIGURATION ENDPOINT]
  • name: a string used to identify the provider when the CLI is used.

  • clientID: the client id provided by the identity provider. used to initialize the authentication flow.

  • clientSecret: the shared secret provided by the identity provider. Some identity providers may use an empty string as a secret. In the context of Certificate Manager, the "client secret" is not actually a secret. Every step client needs to use it to initiate the SSO flow.

  • configurationEndpoint: the endpoint used by the CA to discover the OpenID Connect configuration and public keys used to validate the tokens.

This command requires Administrator privileges on the Authority. The terminal will prompt you to enter your email and perform a single sign-on flow via the smallstep dashboard.

No admin credentials found. You must login to execute admin commands.
✔ Please enter admin name/subject (e.g., name@example.com): authority-admin@yourco.com
✔ Provisioner: authority-admin (OIDC) [client: 4b5c5791-8103-4817-8bb7]
Your default web browser has been opened to visit:

Upon completion, your OIDC provisioner will be created. It will appear on your smallstep dashboard authority detail page.

Step 3 - Enable self-service single sign-on certificates.

From the user's perspective, when requesting a certificate, step detects the OIDC provisioner and initiates the OAuth login flow automatically:

$ step ca certificate developer@yourco.com developer.crt developer.key ✔ CA: CA URL ✔ Certificate: developer.crt ✔ Private Key: developer.key
$ step certificate inspect --short developer.crt X.509v3 TLS Certificate (ECDSA P-256) [Serial: 2581...6739] Subject: 115449349109627210866 developer@yourco.com Issuer: Smallstep Intermediate CA Provisioner: IDP [ID: 6504....com] Valid from: 2019-06-20T18:21:52Z to: 2019-06-21T18:21:52Z

4. Authorize a Provisioner Admin who can issue custom certificates (optional)

By default, an Authority will map the email address in the IDP identity token to a SAN in the certificate. If a user tries to get a certificate with a name that does not match the email address in the IDP identity token, the request will fail.

Provisioner Admins can override this default behavior and issue a certificate with any SANs. To add a Provisioner Admin, update the provisioner you created in step 2:

$ step ca provisioner update [name] --admin=[admin-email]

The admin email address should match the address they use to sign in on the IdP. Use the --admin flag multiple times to add multiple administrators.

Once updated, the provisioner admins can use the single sign-on workflow to create a certificate with any SAN:

$ step ca certificate example.com example.crt example.key ✔ Provisioner: okta (OIDC) [client: 0oacyaoh7tDcyYUbL357] Your default web browser has been opened to visit: https://yourco.okta.com/oauth2/v1/authorize?client_id... ✔ CA: CA URL ✔ Certificate: example.crt ✔ Private Key: example.key

Try it today

Create a Smallstep account and start issuing self-serve single sign-on certificates to all your developers.

Prefer speaking to a human? Schedule time to talk with Smallstep.