From 599d1b1f99ddcd998240407084c8cea568356797 Mon Sep 17 00:00:00 2001 From: Rob Gaston Date: Fri, 13 Jan 2023 15:12:10 -0800 Subject: [PATCH 1/4] adds documentation for external oauth config --- docs/settings-beyond-the-ui.txt | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/settings-beyond-the-ui.txt b/docs/settings-beyond-the-ui.txt index 8c9d2947..39de8a11 100644 --- a/docs/settings-beyond-the-ui.txt +++ b/docs/settings-beyond-the-ui.txt @@ -178,3 +178,34 @@ To configure what group new users are put into, add the following lines of code USER_SIGNUP_GROUP = 'Crowdsource Editor' If you would like to change which group new users are added to, replace 'Crowdsource Editor' with the group you would like to use. + +Using SSO with an external oAuth provider +----------------------------------------- + +Users can be routed through an external oAuth provider for authentication based on their email's domain. + +Your arches application will need to use SSL and be configured with an application ID from your provider. This application ID will need to be configured with a redirect URL to your Arches application at auth/eoauth_cb, for example: https://qa.archesproject.org/auth/eoauth_cb + +Once your application is set up with the provider, you can configure Arches to use it by updating EXTERNAL_OAUTH_CONFIGURATION, for example using an Azure AD tenant could look something like this: + +.. code-block:: python + + EXTERNAL_OAUTH_CONFIGURATION = { + # these groups will be assigned to oAuth authenticated users on their first login + "default_user_groups": ["Resource Editor"], + # users who enter an email address with this domain will be authenticated through external oAuth + "user_domain": "archesproject.org", + # claim to be used to assign arches username from + "uid_claim": "preferred_username", + # application ID and secret assigned to your arches application + "app_id": "my_app_id", + "app_secret": "my_app_secret", + # provider scopes must at least give Arches access to openid, email and profile + "scopes": ["User.Read", "email", "profile", "openid", "offline_access"], + # authorization, token and jwks URIs must be configured for your provider + "authorization_endpoint": "https://login.microsoftonline.com/my_tenant_id/oauth2/v2.0/authorize", + "token_endpoint": "https://login.microsoftonline.com/my_tenant_id/oauth2/v2.0/token", + "jwks_uri": "https://login.microsoftonline.com/my_tenant_id/discovery/v2.0/keys" + # enforces token validation on authentication, AVOID setting this to False + "validate_id_token": True, + } From d3176b63a6abc0148ce05dd612d9cf9b782a86d9 Mon Sep 17 00:00:00 2001 From: Rob Gaston Date: Fri, 13 Jan 2023 15:53:59 -0800 Subject: [PATCH 2/4] updates sso config for multiple domains --- docs/settings-beyond-the-ui.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/settings-beyond-the-ui.txt b/docs/settings-beyond-the-ui.txt index 39de8a11..19958977 100644 --- a/docs/settings-beyond-the-ui.txt +++ b/docs/settings-beyond-the-ui.txt @@ -193,8 +193,8 @@ Once your application is set up with the provider, you can configure Arches to u EXTERNAL_OAUTH_CONFIGURATION = { # these groups will be assigned to oAuth authenticated users on their first login "default_user_groups": ["Resource Editor"], - # users who enter an email address with this domain will be authenticated through external oAuth - "user_domain": "archesproject.org", + # users who enter an email address with one of these domains will be authenticated through external oAuth + "user_domains": ["archesproject.org"], # claim to be used to assign arches username from "uid_claim": "preferred_username", # application ID and secret assigned to your arches application From f44d19d524ff6870049dfe957429006408670510 Mon Sep 17 00:00:00 2001 From: Rob Gaston Date: Fri, 13 Jan 2023 16:00:22 -0800 Subject: [PATCH 3/4] nit --- docs/settings-beyond-the-ui.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/settings-beyond-the-ui.txt b/docs/settings-beyond-the-ui.txt index 19958977..67855aec 100644 --- a/docs/settings-beyond-the-ui.txt +++ b/docs/settings-beyond-the-ui.txt @@ -179,10 +179,10 @@ To configure what group new users are put into, add the following lines of code If you would like to change which group new users are added to, replace 'Crowdsource Editor' with the group you would like to use. -Using SSO with an external oAuth provider +Using SSO with an external OAuth provider ----------------------------------------- -Users can be routed through an external oAuth provider for authentication based on their email's domain. +Users can be routed through an external OAuth provider for authentication based on their email's domain. Your arches application will need to use SSL and be configured with an application ID from your provider. This application ID will need to be configured with a redirect URL to your Arches application at auth/eoauth_cb, for example: https://qa.archesproject.org/auth/eoauth_cb @@ -191,9 +191,9 @@ Once your application is set up with the provider, you can configure Arches to u .. code-block:: python EXTERNAL_OAUTH_CONFIGURATION = { - # these groups will be assigned to oAuth authenticated users on their first login + # these groups will be assigned to OAuth authenticated users on their first login "default_user_groups": ["Resource Editor"], - # users who enter an email address with one of these domains will be authenticated through external oAuth + # users who enter an email address with one of these domains will be authenticated through external OAuth "user_domains": ["archesproject.org"], # claim to be used to assign arches username from "uid_claim": "preferred_username", From 7d4b6ce7c71b5dcd944b0611f4a218258efcefc9 Mon Sep 17 00:00:00 2001 From: Rob Gaston Date: Fri, 13 Jan 2023 16:12:03 -0800 Subject: [PATCH 4/4] clarifies SSO and use case --- docs/settings-beyond-the-ui.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/settings-beyond-the-ui.txt b/docs/settings-beyond-the-ui.txt index 67855aec..433de029 100644 --- a/docs/settings-beyond-the-ui.txt +++ b/docs/settings-beyond-the-ui.txt @@ -179,10 +179,10 @@ To configure what group new users are put into, add the following lines of code If you would like to change which group new users are added to, replace 'Crowdsource Editor' with the group you would like to use. -Using SSO with an external OAuth provider ------------------------------------------ +Using Single Sign-On With an External OAuth Provider +---------------------------------------------------- -Users can be routed through an external OAuth provider for authentication based on their email's domain. +To take advantage of single sign-on using an organiztion's identity provider, users can be routed through an external OAuth provider for authentication based on their email's domain. Your arches application will need to use SSL and be configured with an application ID from your provider. This application ID will need to be configured with a redirect URL to your Arches application at auth/eoauth_cb, for example: https://qa.archesproject.org/auth/eoauth_cb