External Apps

Adding non-native stackspin apps

It is possible to install non-native Stackspin apps to the dashboard and use Stackspin to log in to that application.

It is required that the application supports OAuth2/OpenID Connect mechanism to authenticate.

This document describes how to add apps. When examples are used, it assumes gitlab is added as external app.

Requirements

  • Provisioning machine

  • Access to kubectl to control the cluster

  • Details of external app requirements

Create oAuth objects in the cluster

In an oauth authorization sequence, the app needs to be authorized by the OAuth2 provider, and uses application credentials to do so. These are the client_id and client_secret. These should be unique per added app. It is used to identify which app is trying to authorize. On top of that, an app has a return url, which is used to return to after authentication. This URL needs to be static and can not contain a wildcards.

Because it is possible the app you are trying to add will be added to Stackspin in the future, it is recommended to prefix the app name with ext-. So if you want to add gitlab as an external app, it is advised to use ext-gitlab as client_id and other references to the app name. This way it can never conflict with naming in Stackspin.

Stackspin requires to register two objects in the cluster to let applications authenticate. The kubernetes objects are:

  • Secret: Containts the app credentials (client_secret and client_id)

  • OAuth2Client: Containts the oAuth configuration for the app

Below are templates for those objects, which can be saved in a yaml file. The client_secret and client_id are free to define by yourself. They need to be the same in your external app, as on the stackspin cluster. We advise the client_id to be identical to ext-{APPNAME}

apiVersion: v1
metadata:
  name: stackspin-ext-{APPNAME}-oauth-variables
  namespace: flux-system
stringData:
  client_id: {CLIENT_ID}
  client_secret: {CLIENT_SECRET}
kind: Secret

Template for the OAuth2Client object:

apiVersion: hydra.ory.sh/v1alpha1
kind: OAuth2Client
metadata:
  name: ext-{APPNAME}-oauth-client
  namespace: flux-system
spec:
  grantTypes:
  - authorization_code
  - refresh_token
  - client_credentials
  hydraAdmin: {}
  metadata: null
  redirectUris:
  - https://APP.HOSTNAME/path/to/callback
  responseTypes:
  - id_token
  - code
  scope: openid profile email stackspin_roles
  secretName: stackspin-ext-{APPNAME}-oauth-variables
  tokenEndpointAuthMethod: client_secret_basic

The latter template configures the specifics of the client. This is a general template, however, it is possible that changes are require to make the template work with the app you want to add.

Most important are:

  • redirectUris: the URL where the APP redirects to after authentication. This is specified by the app.

  • tokenEndPointAuthMethod: Two common endpoint methods are client_secret_basic and client_secret_post. Verify with your app which is used by your application.

Install objects in your cluster

Once you created the object, you need to install them in your cluster:

$ kubectl apply -f ext-appname-secret.yaml
$ kubectl apply -f ext-appname-oauth.yaml

Configure your application

Now it is time to configure your application. How to do this really depends on the application you are using. Read the documentation on how to configure oAuth. For this you will need the client_id and client_secret.

Once this is completed, you should already be able to login with a Stackspin admin user. Other users don’t have access to the application by default. You can configure user access through the Stackspin dashboard after finishing this guide.

Required information to configure your application:

Note

Stackspin provides as sub a unique identifier. This is the internal ID of the user and is unique. Even if a use changes their username or email. How information Stackspin shares with the app is used to map (or create) local users differs per application. By default, email and preferred_username are shared with the application.

Configure the dashboard

Now your application is working, you want to add it to the dashboard, so you can actually assign roles for the app to other users.

This is done by adding the application from the CLI:

$ kubectl exec -n stackspin deploy/dashboard-backend -- \
    flask cli app create ext-APPNAME "App Name" https://APP.DOMAIN

Note

The last argument is an URL. If the URL is specified, the app is handled as an external application. For internal/Stackspin managed applications this value should not be specified and is determined by Stackspin iteself.

Done! You now added the app and it should show up at the dashboard. It should be possible to assign roles from the web-interface.