Open Source

Connect your identity provider and issue X.509 certificates for user authentication to services

Smallstep makes running your own private CA and managing certificates for internal services easy. Open source step-ca also supports OAuth for provisioning X.509 certificates for user authentication. We make it easy for developers to obtain a certificate via single sign-on using your existing identity provider (Google, Okta, Active Directory, ...). Issued certificates are signed by the CA and trusted by all your workloads and services so you can use mTLS everywhere.

Any mention of "certificates" in this document refers to X.509 certificates.

About this tutorial

Learn how to obtain an X.509 certificate for user authentication via single sign-on using Google credentials.

Examples include copy/paste code blocks and specific commands for G-Suite.

When complete, you will have connected your identity provider and issued X.509 certificates for user authentication.

Estimated effort: Reading time ~3 mins, Lab time ~10 to 60 mins.

If you run into any issues please let us know in GitHub Discussions.

Requirements

Open Source - This tutorial assumes you have initialized and started up a step-cainstance using the steps in Getting Started.

Smallstep Certificate Manager - Please visit the Certs for Humans documentation instead of using this tutorial to connect your identity provider to Certificate Manager.

Personal certificates via OAuth OpenID Connect

User identities are usually already managed by your existing G-Suite, Okta, Salesforce, or Microsoft Azure Active Directory identity provider. IDPs leverage a single database of user accounts to provide single sign on login to a wide array of applications and services. The OpenID Connect protocol is commonly used to facilitate the exchange between the application, user, and IDP. You can leverage OpenID Connect to authenticate with step-ca to make issuance of personal certificates simple for your whole team.

Here's how to obtain a user certificate using an OAuth token from G-Suite.

1. Add an OpenID Connect provisioner for your G-Suite

Add a G-suite provisioner:

step ca provisioner add Google --type oidc \
    --client-id 650445034027-jsjdrkiskeq9ke99ud2rqkst82ft8uch.apps.googleusercontent.com \
    --client-secret 6Q7lGMua_Oox4nA92QBXYypT \
    --configuration-endpoint https://accounts.google.com/.well-known/openid-configuration \
    --domain smallstep.com --domain gmail.com

2. Reload the CA

You'll need to restart or SIGHUP step-ca in order to pick up the configuration changes.

kill -SIGHUP $(ps aux | grep step-ca | grep -v grep | awk '{print $2}')

3. Get a personal certificate using your G-Suite account

Be sure to specify your G-Suite email address (the command's first argument) and select the "Google" provisioner from the dropdown:

$ step ca certificate davey.oauth.jones@gmail.com personal.crt personal.key

Use the arrow keys to navigate: ↓ ↑ → ←
What provisioner key do you want to use?
    pDpbCsI8Thvci7EqyJJY7AoUIadufTeZQnAcBCwGuHE (admin)
  ▸ 650445034027-jsjdrkiskeq9ke99ud2rqkst82ft8uch.apps.googleusercontent.com (Google)

Unlike regular JWK-based provisioners no password prompt will come up in the terminal. Instead expect the default browser to open the G-Suite login screen. After successfully logging-in the CA will issue a certificate for the respective user.

$ step certificate inspect --short personal.crt
X.509v3 TLS Certificate (ECDSA P-256) [Serial: 1445...0545]
  Subject:     113900523962383213156
               davey.oauth.jones@gmail.com
  Issuer:      Local CA Intermediate CA
  Provisioner: Google [ID: 6504....com]
  Valid from:  2019-03-20T18:17:55Z
          to:  2019-03-21T18:17:55Z

4. Test out your new personal X.509 Certificate

Let's bring up an example server configured to accept connections over mTLS.

Below is some python code we'll use for our example server:

import BaseHTTPServer, ssl
class H(BaseHTTPServer.BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200); self.send_header('content-type', 'text/html; charset=utf-8'); self.end_headers()
        san = self.connection.getpeercert().get('subjectAltName')[0][1]
        self.wfile.write(b'\n\xf0\x9f\x91\x8b Hello '+san+'! Welcome to mTLS \xf0\x9f\x94\x92\xe2\x9c\x85\n\n')
httpd = BaseHTTPServer.HTTPServer(('', 8443), H)
httpd.socket = ssl.wrap_socket (httpd.socket, server_side=True, keyfile="localhost.key", certfile="localhost.crt",
                                cert_reqs=ssl.CERT_REQUIRED, ca_certs="root_ca.crt")
httpd.serve_forever()

Before running the server, let's create a server X.509 certificate and key pair:

step ca localhost localhost.crt localhost.key

Now let's run our Python example server:

python server.py

Finally we're ready to to test our personal certificate using curl. All we need to do is provide a root certificate for client-side server authentication and our personal certificate and private key to pass the server-side client authentication.

curl --cacert $(step path)/certs/root_ca.crt --cert personal.crt --key personal.key https://localhost:8443

Success! Using OpenID Connect to make personal X.509 certificates for your teams is an easy and powerful way to unlock strong identity for everybody, everywhere.