Skip to content

Single Sign-On

You can enable authentication via OpenID Connect and OAuth2 using the OpenFaaS REST API. This functionality is part of of the OpenFaaS Premium Subscription.

Try a walk-through with Okta

The easiest way to try Single Sign-On with OpenFaaS is to follow a complete walk-through. We have one for Okta here.

Deploy SSO using the helm chart (advanced)

You will need two DNS A records and to enable Ingress for your Kubernetes cluster. In the example below the sub-zone is used, however you can use a top-level domain or your own sub-zone.

  • Gateway -
  • Auth -

Use arkade or helm and pass the following overrides, or edit your values.yaml file:

export PROVIDER=""              # Set this to "azure" if using Azure AD.
export LICENSE=""               # Obtain a trial from OpenFaaS Ltd, see above for instructions.
export DOMAIN=""

arkade install openfaas \
  --set oauth2Plugin.enabled=true \
  --set oauth2Plugin.provider=$PROVIDER \
  --set oauth2Plugin.license=$LICENSE \
  --set oauth2Plugin.insecureTLS=false \
  --set oauth2Plugin.scopes="openid profile email" \
  --set oauth2Plugin.jwksURL= \
  --set oauth2Plugin.tokenURL= \
  --set oauth2Plugin.audience=https://gw.$DOMAIN \
  --set oauth2Plugin.authorizeURL= \
  --set oauth2Plugin.welcomePageURL=https://gw.$DOMAIN \
  --set oauth2Plugin.cookieDomain=.$DOMAIN \
  --set oauth2Plugin.baseHost=https://auth.$DOMAIN \
  --set oauth2Plugin.clientSecret=$OAUTH_CLIENT_SECRET \
  --set oauth2Plugin.clientID=$OAUTH_CLIENT_ID 

The authorizeURL, tokenURL and jwksURL contain my personal tenant URL, remember to customize this to your own from Auth0, or your IDP.

For cookieDomain - set the root URL of both of your sub-domains i.e., this is so that the cookie set by the auth service can be used by the gateway.

You should also create an additional Ingress and TLS certificate as per below.

You can use the openfaas-ingress arkade app, or create an Ingress record manually.

  arkade install openfaas-ingress \
  --domain gw.oauth.example \
  --oauth2-plugin-domain auth.oauth.example \

This is an example of a manual Ingress record created without using arkade.

apiVersion: extensions/v1beta1
kind: Ingress
  name: openfaas-auth
  namespace: openfaas
  annotations: letsencrypt-prod nginx
  - host: auth.oauth.example
      - backend:
          serviceName: oauth2-plugin
          servicePort: 8080
        path: /
  - hosts:
    - auth.oauth.example
    secretName: openfaas-auth

Gain access via the UI

The UI uses the code grant flow.

Just visit the gateway and you will be redirected to your IDP to log in:

Gain access via the CLI (interactive)

The CLI uses the implicit grant flow for interactive usage such as your daily workflow from your own computer / workstation.

Run the following:

faas-cli auth \
  --auth-url \
  --audience \
  --client-id "${OAUTH_CLIENT_ID}"

You will receive a token on the command-line and same will be saved to openfaas config file. faas-cli will read the token and pass it for future commands which requires authentication.

You can also export it with export TOKEN="" and use it with any command: faas-cli list --token="${TOKEN}"

See also: faas-cli README

Gain access via the CLI for CI (non-interactive / machine-usage)

Non-inactive or machine-usage is where you need to access the gateway and you cannot follow a web-browser to authenticate. Here, you need to create a special application in your IDP. It will usually be called a "Machine Application" and has a client_id and client_secret, these are comparable to a username and password.

You will need to use the client credentials flow.

You will need this flow for any actions taken within a cron-job, broker, CI/CD job or similar server-access.

You can use faas-cli login:

faas-cli login \
 --username ${OAUTH_CLIENT_ID} \
 --password ${OAUTH_CLIENT_SECRET}

Now run any command as usual such as faas-cli list or faas-cli deploy. The secrets will be fetched from ~/.openfaas/config.yml.

Note: some providers may also support obtaining a token for this flow, such as Auth0:

faas-cli auth \
  --grant client_credentials \
  --auth-url \
  --client-id "${OAUTH_CLIENT_ID}" \
  --client-secret "${OAUTH_CLIENT_SECRET}"\

You will receive a token on the command-line which is also saved in ~/.openfaas/config.yml.

The faas-cli will read the token and pass it for future commands which requires authentication, you can also export it with export TOKEN="" and use it with any command: faas-cli list --token="${TOKEN}"

See also: faas-cli README