Skip to content

Update Okta examples (#2185) #2249

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 10, 2025
Merged

Update Okta examples (#2185) #2249

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion modules/ROOT/pages/tutorial/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,5 @@ The following step-by-step tutorials cover common operational tasks or otherwise
* xref:tutorial/neo4j-admin-import.adoc[Neo4j Admin import] -- This tutorial provides detailed examples to illustrate the capabilities of importing data from CSV files with the command `neo4j-admin database import`.
* xref:tutorial/tutorial-composite-database.adoc[Set up and use a Composite database] -- This tutorial walks through the basics of setting up and using Composite databases.
* xref:tutorial/access-control.adoc[Fine-grained access control] -- This tutorial presents an example that illustrates various aspects of security and fine-grained access control.
* xref:tutorial/tutorial-sso-configuration.adoc[Configuring Neo4j Single Sign-On (SSO)] -- This tutorial presents examples and solutions to common problems when configuring SSO.
* xref:tutorial/tutorial-sso-configuration.adoc[Configuring Neo4j Single Sign-On (SSO)] -- Examples and solutions to common problems when configuring SSO.
* xref:tutorial/tutorial-clustering-docker.adoc[Deploy a Neo4j cluster in a Docker container] -- This tutorial walks through setting up a Neo4j cluster on your local computer for testing purposes.
113 changes: 74 additions & 39 deletions modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,32 +47,52 @@ Thus, changing the username claim from `sub` is not recommended.

== Okta

=== Access token
The following examples show how to configure Okta for authentication and authorization using access tokens and ID tokens.
It assumes that you are using Okta Developer Edition Service.
For the complete guide on how to customize tokens returned from Okta with a groups claim, see the https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/[Okta official documentation].

This example shows how to configure Okta for authentication and authorization using access tokens.
=== Configure the client

. From the left-hand side of the Okta dashboard, navigate to *Applications* and click *Create App Integration*.
. Select *OIDC - OpenID Connect* for Sign-in method and *Single-Page Application* for Application type.
. Click *Next*.
. Configure the client with the appropriate redirect URI.
You can skip the group assignments in this step:
+
image::sso-configuration-tutorials/oidc-okta-client-creation.png[title="Okta OIDC client creation"]
+
image::sso-configuration-tutorials/oidc-okta-client-config-a.png[title="Okta OIDC client configuration"]
.. Add a name for the app integration.
.. Add the *Sign-in redirect URIs*, for example, `http://localhost:7474/browser/?idp_id=okta&auth_flow_step=redirect_uri`.
This URI will accept returned token responses after successful authentication.
. Add the *Sign-out redirect URIs*, for example, `http://localhost:7474/browser/`.
. In the *Assignments* section, select *Skip group assignment* for now.
. Click *Save*.
. Take note of the Client ID.
You will need it later when configuring the Okta parameters and the Well-known OpenID Connect endpoint in the _neo4j.conf_ file.

=== Assign Okta groups to the application

. From the left-hand side of the Okta dashboard, navigate to *Dashboard -> Directory -> Groups*, and click *Add Group*.
. Add a name for the group, for example, `engineers`, and click *Save*.
. Click the group you just created and then click *Assign people*.
. Add users to the group.
Users can be added to a group either on user creation or by editing the group.
. Assign the group to an application.
.. Click *Applications* and then *Assign Applications*.
.. Select the application you created earlier and click *Assign*.

. Take note of the Client ID and the Okta domain.
You will need them later when configuring the Okta parameters and the Well-known OpenID Connect endpoint in the _neo4j.conf_ file:
+
image::sso-configuration-tutorials/oidc-okta-client-config-b.png[title="Okta OIDC client configuration"]
=== Access token

. Create groups in Okta, assign users to them (the user can be added to a group either on user creation or editing the group), and map them in the `neo4j.conf` to native groups:
+
image::sso-configuration-tutorials/oidc-okta-server-groups.png[title="Okta OIDC server groups"]
This example shows how to configure Okta for authentication and authorization using access tokens and how to configure Neo4j to use them.

==== Add a groups claim to access tokens

. From the left-hand side of the Okta dashboard, navigate to *Security -> API*.
. Click the default authorization server (the one that shows `api://default` as audience) to return the `groups` claim in access tokens:
.. On the *Claims* tab, click *Add Claim*.
.. Add a claim with the name `groups`.
.. From the *Value type* dropdown, select *Groups*.
.. From the Filter dropdown, select *Matches regex* and the value `.*`.
.. Click *Create*.

==== Configure Neo4j

. Configure the default authorization server (the one that shows `api://default` as audience) to return the `groups` claim in access tokens:
+
image::sso-configuration-tutorials/oidc-okta-authz-server.png[title="Okta OIDC authorization server"]
+
image::sso-configuration-tutorials/oidc-okta-server-claims.png[title="Okta OIDC server claims"]
+
. Configure Neo4j to use Okta authentication by configuring the following settings in the _neo4j.conf_ file:
+
[source, properties]
Expand All @@ -81,11 +101,11 @@ dbms.security.authentication_providers=oidc-okta
dbms.security.authorization_providers=oidc-okta
dbms.security.oidc.okta.display_name=Okta
dbms.security.oidc.okta.auth_flow=pkce
dbms.security.oidc.okta.well_known_discovery_uri=https://dev-21056049.okta.com/oauth2/default/.well-known/openid-configuration
dbms.security.oidc.okta.well_known_discovery_uri=https://dev-54101110.okta.com/oauth2/default/.well-known/oauth-authorization-server
dbms.security.oidc.okta.audience=api://default
dbms.security.oidc.okta.claims.username=sub
dbms.security.oidc.okta.claims.groups=groups
dbms.security.oidc.okta.params=client_id=0oa3oq6uw3uSOBf8y5d7;response_type=code;scope=openid profile email
dbms.security.oidc.okta.params=client_id=0oao2rybx5hIERt5W5d7;response_type=code;scope=openid profile email
dbms.security.oidc.okta.authorization.group_to_role_mapping= "engineers" = admin; \
"collaborators" = reader
----
Expand All @@ -101,41 +121,57 @@ image::sso-configuration-tutorials/oidc-okta-successful-login.png[title="Okta OI

=== ID token

This example shows how to configure Okta for authentication and authorization using ID tokens.
This example shows how to configure Okta for authentication and authorization using ID tokens and the how to configure Neo4j to use them.

. Follow the first two steps from the instructions for xref:#_access_token[Access token].
==== Add a groups claim to ID tokens

. Create the claims as indicated:
+
image::sso-configuration-tutorials/okta-claims.svg[title="Okta claim creation panel"]
You can add a groups claim to ID tokens to configure authentication and authorization using ID tokens.

. From the left-hand side of the Okta dashboard, navigate to *Security -> API*.
. Click the default authorization server (the one that shows `api://default` as audience) to return the `groups` claim in access tokens:
.. On the *Claims* tab, click *Add Claim*.
.. Add a claim with the name `groups`.
.. From the *Include in token type* dropdown, select *ID Token*.
.. From the *Value type* dropdown, select *Groups*.
.. From the Filter dropdown, select *Matches regex* and the value `.*`.
.. Click *Create*.
. Add a claim with the name `userid` and the value type `User ID`.
+
[NOTE]
====
In the case of access tokens, a default sub is already provided automatically.
However, for ID tokens, the name you give to your claim needs to be also indicated in the configuration `dbms.security.oidc.okta.claims.username=userid`.
The `userid` claim is not included in the ID token by default like the default `sub` claim for access tokens, thus you need to add it manually.
The name you give to your claim needs to be also indicated in the configuration `dbms.security.oidc.okta.claims.username=userid` in the _neo4j.conf_ file.
====
+
. Configure the default authorization server (the one that shows api://default as audience) as indicated:
.. Click *Add Claim*.
.. Add a claim with the name `userid`.
.. From the *Include in token type* dropdown, select *ID Token*.
.. From the *Value type* dropdown, select *Expression*.
.. In the *Value* field, type `(appuser !=null) ? appuser.userName : app.clientId`.
.. Click *Create*.

==== Configure Neo4j

. Configure Neo4j to use Okta authentication by configuring the following settings in the _neo4j.conf_ file:
+
[source, properties]
----
dbms.security.authentication_providers=oidc-okta, native
dbms.security.authorization_providers=oidc-okta
dbms.security.oidc.okta.display_name=Okta
dbms.security.oidc.okta.auth_flow=pkce
dbms.security.oidc.okta.well_known_discovery_uri=https://trial-2696363.okta.com/oauth2/default/.well-known/openid-configuration
dbms.security.oidc.okta.audience=0oa42hwrygsUCFlLO697
dbms.security.oidc.okta.well_known_discovery_uri=https://dev-54101110.okta.com/oauth2/default/.well-known/oauth-authorization-server
dbms.security.oidc.okta.audience=0oao2rybx5hIERt5W5d7
dbms.security.oidc.okta.claims.username=userid
dbms.security.oidc.okta.claims.groups=groups
dbms.security.oidc.okta.params=client_id=0oa42hwrygsUCFlLO697;response_type=code;scope=openid profile email
dbms.security.oidc.okta.params=client_id=0oao2rybx5hIERt5W5d7;response_type=code;scope=openid profile email
dbms.security.oidc.okta.authorization.group_to_role_mapping="admin_group" = admin;
dbms.security.oidc.okta.config=token_type_principal=id_token;token_type_authentication=id_token
----
+
. You should now find the audience under Okta's sign-on tab:
+
image::sso-configuration-tutorials/okta-sign-on-tab.svg[title="Okta's sign-on tab"]
+
[TIP]
====
You can find the audience parameter under *OpenID Connect ID Token* of your application on the *Sign On* tab.
====
. (Optional) If you want control the authentication and authorization on a user level, configure xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] to `true` in the _neo4j.conf_ file.
This setting mandates that users with the relevant auth provider attached to them must exist in the database before they can authenticate and authorize with that auth provider.
For information on how to create users in this mode, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users].
Expand Down Expand Up @@ -221,7 +257,6 @@ image::sso-configuration-tutorials/oidc-azure-client-creation.png[title="Entra O
The redirect URI `http://localhost:7474/browser/?idp_id=azure&auth_flow_step=redirect_uri` is the URI that will accept returned token responses after successful authentication.
. Click *Register*.


==== Configure Neo4j
. After the successful app creation, on the app's *Overview* page, find the Application (client) ID value. Use it to configure the following properties in the _neo4j.conf_ file.
+
Expand Down