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}`

.. code:: yaml

    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: 

.. code:: yaml

    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:

.. code:: console

   $ 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:

- SSO url: https://sso.YOUR-DOMAIN/
- Authorize URL: /oauth2/auth
- Token URL: /oauth2/token
- Userinfo: /userinfo

.. 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:

.. code:: console

   $ 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.