Issuer URI

Before you can apply an AuthServer you need an issuer URI. This issuer URI is the entry point for its clients and their end-users. It needs to be reachable by clients, end-users and the AppSSO operator. Therefore, we need to configure a Service and a form of ingress for the AuthServer to receive traffic.

It is essential to configure Ingress with HTTPS. An authorization server is a critical piece of your security. Using plain HTTP is discouraged. Refer to External access with TLS section for more details on securing traffic.

🙇🏻‍ This section benefits from your input. Please, share feedback in our Slack channel #app-sso.

Configure a Service for AuthServer

⚠️ If you are deploying your Service with kapp make sure to set the annotation kapp.k14s.io/disable-default-label-scoping-rules: "" to avoid that kapp amends Service.spec.selector.

To create a Service for an AuthServer it must select the authorization server’s Deployment and configure ports as follows:

---
apiVersion: v1
kind: Service
metadata:
  name: my-authserver # please, edit
  namespace: authservers # please, edit
  annotations:
    kapp.k14s.io/disable-default-label-scoping-rules: ""
spec:
  type: NodePort
  selector:
    app.kubernetes.io/part-of: my-authserver # replace this with your AuthServer's name
    app.kubernetes.io/component: authorization-server
  ports:
    - port: 80
      targetPort: 8080

Once you have configured ingress with HTTPS for this Service you should have an issuer URI you can use for your Authserver:

spec:
  issuerURI: https://my-authserver.my-domain

Note: This issuerURI that you add to the Authserver config must be the same as Service’s Ingress or LoadBalancer you configured.

If everything goes well, the IssuerURIReady condition in AuthServer.status.conditions will have status: "True". If not, it will tell you why.

If you need to configure a plain HTTP issuer URI, see unsafe configuration

Enabling external access with TLS

This section will step you through the process of enabling TLS on your authorization server using LetsEncrypt.


👉 The following guide should be used as an example of an approach you can take, and not necessarily the only approach that may be feasible.

🧪 The following guide has been verified using Amazon Elastic Kubernetes Service(EKS) and Google Kubernetes Engine (GKE).


Prerequisites

You must have already created a Service resource for your authorization server.

This guide will be based on the following example prerequisite values (your values will differ):

TAP values contains the following fields:

  • shared.ingress_domain: example.com
  • contour.envoy.service.type: LoadBalancer

AuthServer custom resource contains the following:

  • .metadata.name: my-auth-server
  • .metadata.namespace: authservers
  • .spec.issuerUri: https://login.example.com <- this is the URL desired for this auth server

Guide

Create a ClusterIssuer resource. This will be the Certificate issuer authority; in this case, the issuer will be LetsEncrypt ‘staging’.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: appsso-letsencrypt-staging
spec:
  acme:
    email: <SERVICE-OPERATOR-EMAIL-ADDRESS> # please, edit
    privateKeySecretRef:
      name: appsso-letsencrypt-staging      # This will be auto-generated for you when this resource is created
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    solvers:
      - http01:
          ingress:
            class: contour

Create a Certificate resource. This will be the TLS certificate that will be attached to the authorization server subdomain.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: appsso-my-authserver
  namespace: authservers
spec:
  commonName: login.example.com    # Please, edit; this should be your Issuer URI, without https prefix
  dnsNames:
    - login.example.com           # This should be your Issuer URI, without https prefix
  issuerRef:
    name: appsso-letsencrypt-staging # This is the name of the ClusterIssuer from above
    kind: ClusterIssuer
  secretName: appsso-my-authserver   # This secret will be created by this Certificate, just give it a good name

Wait for the Certificate to be issued:

kubectl get certificate appsso-my-authserver --namespace authservers -o wide --watch

It should eventually look like:

NAME                   READY   SECRET                 ISSUER                       STATUS                                          AGE
appsso-my-authserver   True    appsso-my-authserver   appsso-letsencrypt-staging   Certificate is up to date and has not expired   45s

Create an HTTPProxy resource. This resource will map the Issuer URI subdomain to the authorization server Service and apply a TLS certificate.

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: appsso-my-authserver
  namespace: authservers
spec:
  virtualhost:
    fqdn: login.example.com           # This should be your Issuer URI, without https prefix
    tls:
      secretName: appsso-my-authserver   # This is the Secret that was created by the Certificate
  routes:
    - conditions:
        - prefix: /
      services:
        - name: my-authserver # please, edit; this is the name of the Service from above
          port: 80

Wait until Status becomes valid:

kubectl get httpproxy appsso-my-authserver --namespace authservers --watch

Once reconciled, the authorization server should be available at: https://login.example.com


⚠️ LetsEncrypt staging does not provide a trusted level certificate verification and so your browser will not trust the certificate, however you may still continue using the authorization server for testing purposes.

👉 Use LetsEncrypt production issuer to certify trusted certificates; be aware of API rate limits. To use LetsEncrypt production, change the field .spec.acme.server to https://acme-v02.api.letsencrypt.org/directory in your ClusterIssuer


Perform a readiness check, by querying the OpenID Connect discovery endpoint:

curl --insecure https://login.example.com/.well-known/openid-configuration

You should receive a 200 OK JSON response with authorization server information.

Further reading

This guide relies on the following sources:

check-circle-line exclamation-circle-line close-line
Scroll to top icon