OAuth Provider

For Authorization and Authentication, Song readily supports two options:

• Keycloak, a highly regarded open-source identity and access management (IAM) service developed by Red Hat

• Ego, Overture's original authorization and authentication solution.

The most suitable platform will depend on your project's specific requirements. Information on setting up both services with Score can be found below.

Keycloak Setup

There are multiple methods of deploying Keycloak, documentation on Keycloak deployment can be found on the Official Keycloak website.

To expedite the setup process using docker, execute the following command in your terminal:

bash

Copy

docker run --name Keycloak -d -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:22.0 start-dev

This command starts Keycloak exposed on local port 8080 and creates an initial admin user with the username admin and password admin

Overture API Key Provider

The Overture API Key provider extends Keycloak's functionality, by adding custom logic that allows Keycloak to interact with Song. The following steps outline how to download and install the Overtures API Key provider.

1. Using the following link download the Overture API Key Provider.
2. Move the keycloak-apikeys.jar file to the provider's folder within Keycloak (opt/keycloak/providers/).
3. Restart the Keycloak server for the updated provider to take effect.

Realm Configuration

Login to the admin console

To access the admin console, navigate to <url>/admin (e.g., localhost:8080/admin) and log in with the credentials made during your Keycloak deployment.

Create a realm

Keycloak supports the creation of realms for managing isolated groups of applications and users. The default realm is named "master," and is intended solely for Keycloak management.

1. Open the Keycloak Admin Console.
2. In the top-left corner, select "master", then choose "Create Realm".
3. Type myrealm in the Realm Name field and select "Create".

Creating a group

As an example, we will create a data submitters group. After, we will configure and apply the appropriate permissions for this group.

1. From the left-hand panel, select "Groups" and click "Create group".

2. Name the group data submitters and select "create".

Creating a User

To populate the realm with its first user:

1. From the Keycloak Admin Console, under your newly created realm from the left-hand menu select "Users" and click "Add User".
2. Input your details, and then click "Create".

Next, a password must be established:

1. At the top of the User details page, select the ""Credentials" tab"
2. Input your Password. To avoid mandatory password updates upon first login set "Temporary" to "Off"
3. Using the newly created username and password login to the Keycloak Account Console accessed from http://localhost:8080/realms/myrealm/account/.

From the Account Console, users can manage their accounts, modify profiles, activate two-factor authentication, and link identity provider accounts.

Application Setup

Before we set up and apply permissions we must create a "client" for the Song API.

1. Re-open your Keycloak admin console located at <url>/admin and confirm you are within your recently created realm.
2. Select "Clients" and then "Create client" and input the following:

3. Select "Next" and turn on Client Authentication, confirm Standard flow is enabled, turn authorization on and then click "next" and then "Save" (Nothing needs to be inputted for login settings).

Configuring your Application

After creating our client, the next step is configuring the resource name, scopes, policies, and permissions. All these settings can be adjusted within the Authorization tab of the client you've just created. To access your client select "Clients" from the left-hand navigation menu and from the "Client list" select the newly created client.

Scopes

Scopes represent actions that users can perform on a particular resource. They define the level of access a user has to a resource, such as reading, writing, updating, or deleting. For more details, checkout the following Keycloak documentation

1. Navigate to the Scopes tab and select "Create Authorization Scope"
2. Create two authorization scopes, one for READ and one for WRITE access.

Resources

Resources are objects or entities that users can interact with, such as a database, a file, or an API endpoint. When defining resources, you assign them to specific scopes, indicating what actions can be performed on those resources. For more details, checkout the following Keycloak documentation

1. From the Resource tab, select "Create Resource".
2. Your first resource is generalized and will not be associated with any specific study or program. Name the resource score, and from the authorization scopes field dropdown select "READ" and "WRITE".
3. Click save and return to the client details page.

Policies

Policies are rules that determine who can access resources based on certain conditions. They encapsulate the logic to decide whether to grant or deny access. Policies can be based on group membership, user attributes, or time-based conditions. For more details, checkout the following Keycloak documentation

1. Select the Policy tab and click "Create Client Policy"
2. From the popup modal select "group policy".
3. Name your policy (e.g., data submission policy) and select "Add groups from the modal check the box next to the Data Submitter group and click "Add" then "Save".

Permissions

Permissions are the final decision-making mechanism connecting resources, scopes, and policies. They define which users or groups can access which resources under what circumstances. Permissions are evaluated based on the evaluation strategy chosen (e.g., Affirmative, Unanimous, or Consensus). Permissions can be resource-based, meaning they apply directly to a resource, or they can be scope-based, meaning they apply to a scope or combination of scopes and resources. For more details, checkout the following Keycloak documentation

1. Select the permissions tab, click "Create Permission" and from the dropdown select "Create resource-based permission.
2. Assign the newly created resource, scope, and policy. Select Affirmative strategy.

Creating a New Study

As mentioned previously, when introducing a new study or program, the creation of an additional resource within Keycloak is required. This includes re-applying policies and permissions to desired users and groups.

To add a new study, create a new resource with the desired name of your study or program (i.e. PROGRAM.study123) and repeat the steps outline above, specficially the Resources, Policies and Permissions sections of configuring your application. Once complete you should have the following:

Integration with Song

Update your .env.song file with the required Keycloak variables, the following code block will help you get started:

bash

Copy

# ============================
# Keycloak Integration
# ============================

SPRING_CONFIG_ACTIVATE_ON_PROFILE=secure

AUTH_SERVER_PROVIDER=keycloak
AUTH_SERVER_TOKENNAME=apiKey
AUTH_SERVER_KEYCLOAK_HOST={{keycloak-host-url}}
AUTH_SERVER_KEYCLOAK_REALM=myrealm
AUTH_SERVER_CLIENTID={{song-client-ID}}
AUTH_SERVER_CLIENTSECRET={{song-client-secret}}
AUTH_SERVER_SCOPE_STUDY_PREFIX=PROGRAM.study123
AUTH_SERVER_SCOPE_STUDY_SUFFIX=.WRITE
AUTH_SERVER_SCOPE_SYSTEM=song.WRITE
AUTH_SERVER_INTROSPECTIONURI={{keycloak-host-url}}/realms/{{keycloak-realm}}/apikey/check_api_key/
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_PUBLIC_KEY_LOCATION={{keycloak-host-url}}/realms/{{keycloak-realm}}/protocol/openid-connect/certs

Replace any default values with the values specific to your environment. The table below summarizes the variables shown above:

Ego Setup

For help installing Ego and the Ego admin UI, please refer to our Ego installation documentation.

If you're using Ego the secure profile is essential. It enables authentication for requests to the Song API via API keys issued by Ego. To set up your Song server with Ego modify your .env.song file as follows:

bash

Copy

# ============================
# Ego Integration (Required)
# ============================
# Configuration for the secure profile
SPRING_PROFILES_ACTIVE=secure

# Ego authentication settings
AUTH_SERVER_URL={{ego-host-url}}/o/check_api_key/
AUTH_SERVER_CLIENTID={{song-client-ID}}
AUTH_SERVER_CLIENTSECRET={{song-client-secret}}
AUTH_SERVER_TOKENNAME={{API-key}}
AUTH_SERVER_SCOPE_STUDY_PREFIX=song.
AUTH_SERVER_SCOPE_STUDY_SUFFIX=.WRITE
AUTH_SERVER_SCOPE_SYSTEM=song.WRITE
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_PUBLIC_KEY_LOCATION={{ego-host-url}}/oauth/token/public_key

Replace placeholders found in {{brackets}} with your values. The table below summarizes the variables outlined above: