For Authorization and Authentication, Score 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.
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:
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
This setup is designated for development and testing purposes and should not be used in production settings. For production deployments, please refer to Configuring Keycloak for Production.
The Overture API Key provider extends Keycloak's functionality, by adding custom logic that allows Keycloak to interact with Score. The following steps outline how to download and install the Overtures API Key provider.
keycloak-apikeys.jar
file to the provider's folder within Keycloak (opt/keycloak/providers/
).If you have previously set up Song with Keycloak, you can skip ahead to the application setup section on this page.
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.
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.
myrealm
in the Realm Name field and select "Create".As an example, we will create a data submitters
group. After, we will configure and apply the appropriate permissions for this group.
data submitters
and select "create".To populate the realm with its first user:
Various configurations can be applied to new users, detailed information can be found within Keycloaks official Server Administration documentation
Next, a password must be established:
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.
Before we set up and apply permissions we must create a "client" for the Score API.
<url>/admin
and confirm you are within your recently created realm.Field | Value |
---|---|
Client Type | OpenID Connect |
Client ID | score-api |
Make sure you have toggled on both "Client Authentication" and "Authorization"
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 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
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
score
, and from the authorization scopes field dropdown select "READ" and "WRITE".When introducing a new study or program, the creation of an additional resource within Keycloak is required. This includes re-applying the following policies, scopes and permissions to desired users and groups.
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
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 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
Affirmative strategy
.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. score.study123
) and repeat the steps outline above, specifically the Resources, Policies and Permissions sections of configuring your application. Once complete you should have the following:
Update your .env.score
file with the required Keycloak variables, the following code block will help you get started:
# ============================# Keycloak Configurations# ============================# Keycloak-specific profile configurationSPRING_PROFILES_ACTIVE=collaboratory,prod,secure# Server and authentication settingsSERVER_PORT=8087SERVER_SSL_ENABLED=false# LoggingLOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=INFOLOGGING_LEVEL_BIO_OVERTURE_SCORE_SERVER=INFOLOGGING_LEVEL_ROOT=INFO# Server Authentication integrationAUTH_SERVER_PROVIDER=keycloakAUTH_SERVER_KEYCLOAK_HOST=http://localhost:8080AUTH_SERVER_KEYCLOAK_REALM=myrealmAUTH_SERVER_URL=http://localhost:8080/realms/{{realmName}}/apikey/check_api_key/AUTH_SERVER_TOKENNAME=apiKeyAUTH_SERVER_CLIENTID=score-apiAUTH_SERVER_CLIENTSECRET=scoresecretAUTH_SERVER_SCOPE_STUDY_PREFIX=score.AUTH_SERVER_SCOPE_UPLOAD_SUFFIX=.WRITEAUTH_SERVER_SCOPE_DOWNLOAD_SUFFIX=.READAUTH_SERVER_SCOPE_DOWNLOAD_SYSTEM=score.WRITEAUTH_SERVER_SCOPE_DOWNLOAD_SUFFIX=.READAUTH_SERVER_SCOPE_UPLOAD_SYSTEM=score.READAUTH_SERVER_SCOPE_UPLOAD_SUFFIX=.WRITESPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWKSETURI=http://localhost:8080/realms/{{realm-name}}/protocol/openid-connect/certs
Replace any default values with the values specific to your environment. The table below summarizes the variables shown above:
Setting | Requirement | Description |
---|---|---|
AUTH_SERVER_PROVIDER | Required | Specify the authentication server provider. In this case, it's set to keycloak . |
AUTH_SERVER_KEYCLOAK_HOST | Required | The host address for the Keycloak server. Default is http://localhost update this variable accordingly. |
AUTH_SERVER_KEYCLOAK_REALM | Required | The realm in Keycloak under which the Score service is registered. Example: myrealm . |
AUTH_SERVER_URL | Required | URL for the Keycloak API endpoint authenticating a user's API key. Specify the full endpoint URL by inserting your realm name. |
AUTH_SERVER_TOKENNAME | Required | Name identifying a token. Keep this as the default value apiKey . |
AUTH_SERVER_CLIENTID | Required | The client ID for the Score application configured in Keycloak. |
AUTH_SERVER_CLIENTSECRET | Required | The client secret for the Score application configured in Keycloak. This can be accessed from the "Client details" under the "Credentials tab" |
AUTH_SERVER_SCOPE_DOWNLOAD_SYSTEM | Required | Scope (permission) for system-level downloads from Score using an API key. Default: score.WRITE . |
AUTH_SERVER_SCOPE_DOWNLOAD_SUFFIX | Required | Suffix after the Song study name when assigning study-level download scopes for Score. Default: .READ . |
AUTH_SERVER_SCOPE_UPLOAD_SYSTEM | Required | Scope (permission) for system-level uploads to Score using an API key. If following the above instrutions for application setup this value will be score-api. . |
AUTH_SERVER_SCOPE_UPLOAD_SUFFIX | Required | Suffix after the Song study name when assigning study-level upload scopes for Score. Default: .WRITE . |
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWKSETURI | Required | URI for JWT JSON Web Key Set (JWK Set) for the OAuth2 resource server. Specify the Keycloak server URI by inserting your realm name. |
SERVER_PORT | Optional | The port number on which the server will listen. Default is 8087 . |
SERVER_SSL_ENABLED | Optional | Indicates whether SSL is enabled for the server. Default is false . |
LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB | Optional | Sets the logging level for Spring Framework's web components. Default is INFO . |
LOGGING_LEVEL_BIO_OVERTURE_SCORE_SERVER | Optional | Sets the logging level for Score Server components. Default is INFO . |
LOGGING_LEVEL_ROOT | Optional | Sets the root logging level. Default is INFO . |
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 Score API via API keys issued by Ego. To set up your Score server with Ego modify your .env.score
file as follows:
# ============================# Ego Configurations# ============================# Configuration for the secure profileSPRING_PROFILES_ACTIVE=secure# Ego authentication settingsAUTH_SERVER_PROVIDER=egoAUTH_SERVER_URL={{auth_server_url}} # e.g., http://localhost:8080/ego/api/oauth/tokenAUTH_SERVER_TOKENNAME={{token_name}} # Default: 'apiKey'AUTH_SERVER_CLIENTID={{client_id}}AUTH_SERVER_CLIENTSECRET={{client_secret}}AUTH_SERVER_SCOPE_DOWNLOAD_SYSTEM={{download_system_scope}} # Default: 'score.READ'AUTH_SERVER_SCOPE_DOWNLOAD_STUDY_PREFIX={{download_study_prefix}} # Default: 'score.'AUTH_SERVER_SCOPE_DOWNLOAD_STUDY_SUFFIX={{download_study_suffix}} # Default: '.READ'AUTH_SERVER_SCOPE_UPLOAD_SYSTEM={{upload_system_scope}} # Default: 'score.WRITE'AUTH_SERVER_SCOPE_UPLOAD_STUDY_PREFIX={{upload_study_prefix}} # Default: 'score.'AUTH_SERVER_SCOPE_UPLOAD_STUDY_SUFFIX={{upload_study_suffix}} # Default: '.WRITE'AUTH_JWT_PUBLIC_KEY_URL={{public_key_url}} # e.g., https://localhost:8443/oauth/token/public_key
Replace placeholders found in {{brackets}}
with your values. The table below summarizes the variables outlined above:
Setting | Requirement | Description |
---|---|---|
AUTH_SERVER_URL | Required | Ego API endpoint URL for API key authentication. |
AUTH_SERVER_TOKENNAME | Required | Token identifier, typically apiKey . |
AUTH_SERVER_CLIENTID | Required | Client ID for Score registered in Ego. |
AUTH_SERVER_CLIENTSECRET | Required | Client secret for Score registered in Ego. |
AUTH_SERVER_SCOPE_DOWNLOAD_SYSTEM | Required | System-level download scope using an API key. |
AUTH_SERVER_SCOPE_DOWNLOAD_STUDY_PREFIX | Required | Prefix for study-level download scopes. |
AUTH_SERVER_SCOPE_DOWNLOAD_STUDY_SUFFIX | Required | Suffix for study-level download scopes. |
AUTH_SERVER_SCOPE_UPLOAD_SYSTEM | Required | System-level upload scope using an API key. |
AUTH_SERVER_SCOPE_UPLOAD_STUDY_PREFIX | Required | Prefix for study-level upload scopes. |
AUTH_SERVER_SCOPE_UPLOAD_STUDY_SUFFIX | Required | Suffix for study-level upload scopes. |
AUTH_JWT_PUBLIC_KEY_URL | Optional | Ego API endpoint for retrieving a user's public key. Specify the endpoint's host and port. Use /oauth/token/public_key . |
For information on setting up uses, groups and applications in Ego, please refer to our documentation on using the Ego admin UI.