/sample-go-mtls-oauth-client

Primary LanguageGoApache License 2.0Apache-2.0

sample-go-mtls-OAuth-client

This is a sample Go OAuth client using mTLS certificates for authentication with Cloudentity’s Authorization Control Plane SaaS. Additionally, this example demonstrates using the Cloudentity Pyron API Gateway.

Prerequisites

  • Docker
  • Golang
  • Signed certificate

To run the sample OAuth client requires two primary tasks and a third, optional, task:

  1. Prepare your Cloudentity SAAS workspace
  2. Run the sample OAuth client app
  3. Prepare the Pyron Authorizer

Configure Cloudentity SAAS workspace

  1. Sign in Cloudentity sign in
  2. Choose your workspace. This example uses the "mtls-workspace" workspace. choose workspace
  3. Go to "Applications" in the left side bar and choose "Create Application". Then choose "Create" workspace overview
  4. Give the new application a name and choose "Server Web Application" create new application
  5. Choose the "Scopes" tab and scroll down and toggle "OpenID" to on scopes overview
  6. Choose the "OAuth" tab and scroll down to "Token Endpoint Authentication Method". Click it and choose "TLS Client Authentication" from the dropdown menu.
  7. While still on the "OAuth" tab scroll down and find "Certificate Metadata". Click it to see the menu. Depending on how you want to enter the information from your certificate choose the appropriate selection. If using the included certs in thie repo choose "TLS_CLIENT_AUTH_SAN_DNS". The textfield beneath this entry will given instructions on what to enter. In this example "TLS_CLIENT_AUTH_SAN_DNS" is chosen so "DNS Name SAN entry" appears above the textfield below. tls configuration
  8. In the textfield below "Certificate Metadata" (if you chose "TLS_CLIENT_AUTH_SAN_DNS" it will have the title "DNS Name SAN entry") enter the appropriate value. For the included cert it is "acp".
  9. Check "Certificate bound access tokens".
  10. Scroll down and choose "Save Changes"
  11. On the right-hand side, choose "Setup a redirect URI for your application". Enter your redirecit URI. For the sample application enter http://localhost:18888/callback then click "Save". redirect url location
  12. While here copy the "Client ID". This will be used in the environment variables for running the sample OAuth client.
  13. On the left navigation menu choose "Settings" settings overview
  14. Choose the "Authorization" tab. settings OAuth tab overview
  15. Scroll to the bottom of the "Authorizations" tab and paste in "Trusted client certificates" your rootCA contents. In the example provided it is the contents of ca.pem. pasting in rootCA

Your workspace is now prepared.

Build and run the Go OAuth client sample

  1. Go to the .env file in the root directory.
  2. Enter your Client ID.
  3. Enter your .well-known URI. The .well-known uri can be found at https://your-tenant.mtls.us.authz.cloudentity.io/your-tenant/default/.well-known/openid-configuration where 'your-tenant' should be replaced by your own tenant ID.
  4. Optionally: Replace the certs in /certs and update .env to use your desired certs.
  5. From the root directory of the project run the following to build and run the sample client app
make run

After successfully starting the application you will see the following console logs:

Login endpoint available at: http://localhost:18888/login
Callback endpoint available at: http://localhost:18888/callback

Using Pyron API Gateway

  1. Sign in Cloudentity sign in
  2. Choose your workspace. This example uses the "mtls-workspace" workspace. choose workspace
  3. Choose "APIs" on the left side bar. choose apis
  4. Choose the "Gateways" tab. choose gateway tab
  5. Choose "Add Gateway". add gateway
  6. Select "Pyron API Gateway" and give it a name, description, and check "Create and bind services automatically". bind services and save
  7. If not selected, choose the "Quickstart" tab. Follow the instructions shown for downloading and running Pyron. choose apis
  8. After running Pyron, go to the .env file in the root of this project repository and change "USE_PYRON" to true and set "X_SSL_CERT_HASH" equal to your "x5t#S256" certificate thumbprint which you can get from the access token retreived above.
  9. Run the sample OAuth client app
make run
  1. Now, after getting an access token you will have the option to choose 'Call Resource Server API' on the access token screen.
  2. Create a sample policy (link below with step by step instructions and screen shots.)
  3. Choose "Policies" on the left menu.
  4. Choose "Create Policy". Choose "API Request" as the Policy type. Give the policy a name and choose "Cloudentity" as the policy language and choose "Create".
  5. In the policy editor, Delete the existing policy. Then click the "+" sign to add a new validator.
  6. Choose "Attributes" then choose "Add field".
  7. From the "Source" drop down choose "Access Token".
  8. In the field, choose "Custom Value" from the drop down menu.
  9. Under "Full Path" enter "cnf.x5t#S256".
  10. Choose "Equals" and from the "Target" drop down choose "Request".
  11. In the "field attribute name" choose "Request Headers".
  12. In "full path" after "headers." enter "x-ssl-cert-hash".
  13. Add another validator again choosing "Attributes" -> "Add Field". The from "Source" choose "Access Token".
  14. Under "Field/attribute" choose "Custom Value".
  15. In "full path" enter "cnf.x5t#S256" and choose "present".

Now if you enter an incorrect hash or omit the header or the hash you will fail the validation.

Documentation

The steps for this example can be found at Cloudentity Run Sample MTLS App

An overview of mTLS-based client Authentication can be found mTLS-based Client Authentication

Authorization Control Plane extensive documentation can be found at Cloudentity Docs

Protecting API on Pyron API Gateway can be found at Protecting API on Pyron API Gateway