Federated Login#

Skalio ID supports external identity providers. See the usecase description for details. The integration is based on the OpenID Connect standard.

Registration#

In order to integrate with one of the supported identity providers, preparation is necessary. Clients, URLs, secrets and identifiers need to be registered and recorded.

Apple#

Changes need to be made on the Apple Developer platform at https://developer.apple.com/. To make changes, Admin privileges are required.

In general, the following steps need to be taken:

  1. Take note of the Team ID, visible in the top right corner next to the team or company name. Currently, Skalio ID supports only a single Apple Team ID. It must be entered into the configuration, using key apple.teamId (in XCode). This ID never changes and is used across all products/apps of this company.
  2. Register or find the App ID at https://developer.apple.com/account/resources/identifiers/list/bundleId.
    • The term Bundle ID is also sometimes used, it refers to the same App ID.
    • The identifier and name represent a specific application for a particular environment. Typically, these are already created by the frontend team.
    • Select the Team ID as App ID Prefix.
    • The App ID describes the application, possibly suffixed with test. Example: com.skalio.spaces.test
    • Note: The app-ID may have been auto-created by XCode already. In this case, it can be renamed as necessary.
    • Activate capabilities:
      • Associated Domains
      • iCloud
      • Sign in with Apple
        • Set the Server to Server Notification Endpoint based on the environment. Example: https://id.skalio.dev/id/v1/oidc/risc
      • If required: push notifications
  3. Register a Service ID at https://developer.apple.com/account/resources/identifiers/list/serviceId.
    • The Service ID shall represent a specific application (e.g. "spaces") for a particular platform (e.g. "production", "test"). Specify a description and identifier accordingly.
      • Identifier: suggestion is to use the frontend web-endpoint hostname in reverse order.
      • Service ID is to be stored in the App configuration, key OIDC_CLIENT_ID_APPLE.
    • Enable Sign in with Apple.
      • Reference the app ID
      • Domains: register the DNS name(s) of the platform
      • Return URLs: register the external URL(s) pointing to the OIDC formpost flow endpoint (see API endpoint). Note: the URL must start with https://.
  4. Create a Key at https://developer.apple.com/account/resources/authkeys/list.
    • The name shall be useful, describing specific application on the particular platform.
    • Enable "Sign In with Apple". Select the primary App ID.
    • After successful registration, Apple calculates an ECDSA private key. This is available for download only once, so please make sure that you save it securely after downloading it.
      • The key must be loaded into the Skalio ID keystore later under an established alias. Example: oidc.apple.spaces. See private keys.
      • Take note of the Key ID, example: QC5H5V6H7J
    • Note: A maximum of two private keys can be generated per primary App ID! Creating multiple keys serves the purpose of key rotation.

Google#

Changes need to be made using the Google Cloud Console https://console.cloud.google.com/. Editor privileges or higher are required.

  1. Create or switch to the project for the specific application with the particular environment.
  2. Select APIs and services.
  3. If not yet done, configure the OAuth Consent Screen.
    • User Type: external
    • App name: Use a name that expresses the app and environment well
    • User support email: select a Google account with access to the project. This should be an email on which the users of your app can communicate with you, e.g. support@novospace.com.
    • Authorised domains: add the domains of the specific app for the particular environment
      • Domain of the product, example novospace.dev.
      • Domain of Skalio ID for the particular environment, example skalio.dev.
      • Note: only the top-level domain must be entered.
    • Developer contact information: add an email address
  4. Switch to Credentials.
  5. Create two OAuth 2.0 Client IDs:
    • iOS
      • Application Type: iOS
      • Name: product name, suffix iOS, (if applicable, suffix with Test).
      • Bundle ID: reference Apple bundle ID / App ID.
      • App Store ID and Team ID can be left empty.
      • Take note of the Client ID.
      • The Client ID is to be stored in the App configuration, key: OIDC_CLIENT_ID_GOOGLE_FOR_IOS
    • web / other:
      • Application Type: Web application
      • Name: product name, suffix web, (if applicable, suffix with Test)
      • Set Authorized Javascript origins:
        • Add base URL, example https://app.novospace.dev.
        • For a test environment, "branch"-URLs may be necessary here, too.
      • Set Authorized redirect URIs:
        • Add static URL to forwarding page, example https://forward.novospace.dev/static/callback.
      • Take note of the Client ID and Client secret.
      • The Client ID is to be stored in the App configuration, key: OIDC_CLIENT_ID_GOOGLE_FOR_NON_IOS
  6. Create service account
    • Name: Novospace Test
    • The Service account ID is generated by google
    • Grant this service account access to the project
      • TODO
    • Open the service account, switch to Keys
    • Create new private key, format JSON
    • Google creates a private key and downloads it to your computer
    • Take note of the key ID, example: 1bc2cf7856d7167fefe73e88185a21b952f5cbbe
    • The key must be loaded into the Skalio ID keystore under an established alias. Example: oidc.google.spaces. See private keys
  7. Enable the RISC API
    • Open APIs and services
    • Select + Enable APIs and services at the top
    • In the search box, filter for risc; select the RISC API
    • Click on Enable
  8. Grant the service account access to the RISC API
    • Note: This step requires Owner privileges
    • Open IAM
    • Select + Grant Access at the top
    • Add principal: In new principals search for and select the service account by its email address
    • Add role: In Select a role search for and select the RISC Configuration Admin role
    • Click on Save

Skalio ID#

Each external identity provider must be registered in Skalio ID. It is mandatory that the identity provider supports OpenID Connect Discovery.

Private keys#

The private keys that were downloaded during the creation of the Apple Service ID and the Google Service account need to be loaded into the java keystore and then distributed to all backend servers.

Since the format of the keys is different for each provider, they are imported into the keystore file manually, using scripts, by the operations team. The keystore file is then distributed to the application servers by the config management system.

The contents of the keystore can be viewed:

  1. Start the Skalio ID shell
  2. keystore list

Example output:

skalio-id> keystore list
This will list entries and their aliases in a keystore.
Configured keystore location: /etc/skalio-id/keystore.jks

Keystore contains 2 entries.
Alias                    | Algorithm    | Priv Key   | Pub Key
---------------------------------------------------------------
com.skalio.id            | EC           | yes        | yes
oidc.apple.spaces        | EC           | yes        | yes
---------------------------------------------------------------

Register OIDC Providers#

  1. Start the Skalio ID shell
  2. If the OIDC provider is not yet there, add it: oidc provider create
    • Provide the OIDC discovery URL
    • Correct the issuer if necessary

Example output:

skalio-id> oidc provider create
OIDC provider creation

This command can be used to register new OpenID Connect providers. Please have the discovery endpoint URL
ready. The command will attempt to import information based on the contents of the discovery.
The discovery endpoint typically ends with URL path /.well-known/openid-configuration

OIDC discovery endpoint > https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration
Fetching discovery document ... OK!

Discovered information:
Issuer           : https://login.microsoftonline.com/{tenantid}/v2.0
Endpoints:
 JWKs            : https://login.microsoftonline.com/common/discovery/v2.0/keys
 Authorization   : https://login.microsoftonline.com/common/oauth2/v2.0/authorize
 Token           : https://login.microsoftonline.com/common/oauth2/v2.0/token
 UserInfo        : https://graph.microsoft.com/oidc/userinfo
 Revocation      : null
Supported interactions:
 Response type   : code, id_token, code id_token, id_token token
 Response mode   : query, fragment, form_post
 Scope           : openid, profile, email, offline_access
 Grant type      : null
Confirm (y/N)? y

Issuer [https://login.microsoftonline.com/{tenantid}/v2.0] > https://login.microsoftonline.com/common/v2.0
Import OpenID Connect provider into the database (y/N)? y
Creating OIDC provider ... OK!

This provider has no registered OpenID Connect contexts yet. These are required to make
the integration work. The following command can be used to register contexts:
> oidc context create

Register OIDC Contexts#

An OIDC context represents a project (Google) or app (Apple).

  1. Start the Skalio ID shell
  2. If the OIDC context is not yet there, add it: oidc context create
    • Select the OIDC provider
    • Provide a name representing the app
    • Provide optional private key alias, private key ID and service account email as required by the OIDC identity provider

Example output:

skalio-id> oidc context create
OIDC Context creation

This command can be used to register new OpenID Connect context to an existing provider.
A context represents a group of OIDC clients belonging to one OIDC provider. It stores
shared information, such as references to a private key.

Please note: if the context has a private key, please make sure it is loaded into the
keystore beforehand.

OIDC provider > https://login.microsoftonline.com/common/v2.0

Name     > Novospace Microsoft
Private Key Alias > oidc.microsoft.spaces
Private Key ID > abc123
Service Account Email >

Issuer          : https://login.microsoftonline.com/common/v2.0
Name            : Novospace Microsoft
Private Key Alias: oidc.microsoft.spaces
Private Key ID  : abc123
Service Account : -- not set --
Confirm (y/N)? y
Register this OpenID Connect context (y/N)? y
Creating OIDC context ... OK!

Register OIDC Clients#

  1. Start the Skalio ID shell

  2. Add the OIDC clients: oidc client create

  3. Apple - non Apple platforms

    • Client ID: use the Service ID
    • Redirect URL: leave blank
    • Client Secret: leave blank, it is calculated automatically
  4. Apple - iOS, macOS
    • Client ID: use the Bundle ID
    • Redirect URL: leave blank
    • Client Secret: leave blank, it is calculated automatically
  5. Google - non iOS
    • Client ID: as per Google Cloud console
    • Redirect URL: as per Google Cloud console
    • Client secret: as per Google Cloud console
  6. Google - iOS
    • Client ID: as per Google Cloud console
    • Redirect URL: Use the custom URL scheme pointing to the bundle ID. Example: com.skalio.spaces:/oauthredirect
      • Frontend: OIDC_GOOGLE_REDIRECT_URL_SCHEME_IOS

Example output:

skalio-id> oidc client create
OIDC client creation

This command can be used to register new OpenID Connect client to an existing provider.
Please have information such as the client ID and redirect URL ready.
Registered clients can be used immediately after registration.

OIDC provider > https://login.microsoftonline.com/common/v2.0
Listing existing contexts of OIDC provider:

ID  | Name                                     | Private key alias
-------------------------------------------------------------------------------------------
4   | Novospace Microsoft                      | oidc.microsoft.spaces
Select by ID > 4

Client ID     > abc123.novospace.on-microsoft.com
Redirect URL  > https://forward.novospace.dev/static/callback
Client Secret > abc123

Issuer          : https://login.microsoftonline.com/common/v2.0
Context         : Novospace Microsoft
Client ID       : abc123.novospace.on-microsoft.com
Redirect URL    : https://forward.novospace.dev/static/callback
Client Secret   : abc123
Confirm (y/N)? y
Register this OpenID Connect client (y/N)? y
Creating OIDC client ... OK!

Register the Google RISC endpoint#

For Google, the RISC endpoint must be registered from within Skalio ID.

  1. Start the Skalio ID shell
  2. Begin RISC registration: google risc-configuration register
    • Enter the RISC endpoint of the environment. Example: https://id.skalio.dev/id/v1/oidc/risc

Example output:

skalio-id> google risc-configuration register
Google OIDC RISC configuration registration

This command can be used to register a stream configuration for Google OIDC apps to start receiving RISC events.
Additionally, this command can be used to update an already registered configuration.

Enter the RISC endpoint you want to register > https://id.skalio.dev/vm124/id/v1/oidc/risc