Okta Configuration using OIDC (preferred over SAML)

Jump to configuration using SAML

Log in to the admin area to Start an OIDC App Integration (these steps follow
https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm
with the insertion of group steps and appendage of access policy steps).

Create a PDC Group

On the left nav bar, visit “Directory” -> “Groups”
Click “Add group”
Set “Name” to PDC
Set “Description” to Users who may access the Philanthropy Data Commons
Click “Save”
Click the newly created “PDC” group
Click “Assign people” and add at least one user.

Create a PDC Application

On the left nav bar, visit “Applications” -> “Applications”
Click “Create App Integration”
Click “OIDC”
Select “Web Application”
Click “Next”
Add “App Name” of Philanthropy Data Commons
Leave “Proof of possession” unchecked
Set “Grant type” to Authorization code only
Set “Sign-in redirect URI” to the endpoint provided by the PDC team, similar
to https://example.org/realms/pdc/broker/foundation-okta-oidc/endpoint
Important: the name following broker/ here needs to match the agreed
alias mentioned above
Clear the “Sign-out redirect URIs” by clicking the X
Under “Assignments” select Limit access to selected groups
Set the “Selected group(s)” to the PDC group created earlier
Click “Save”
Confirm under “Login” that “Login initiated by” is App Only
Share the “Client ID” from “Client Credentials” with the PDC team
Under “Client Credentials” click “Edit”
Set “Client authentication” to Public key / Private key
Check “Require PKCE as additional verification”
Under “Public Keys” -> “Configuration”, check “Use a URL to fetch keys…”
Set the URL to the JWKS URL of the PDC Keycloak server, provided by the PDC
team, similar to
https://example.org/realms/pdc/protocol/openid-connect/certs
Click “Save”
Click “Save” at an “Existing client secrets will no longer be used” warning.

Create an Access Policy and Rule for the Authorization Server

On the left nav bar, visit “Security” -> “API” (way down there)
Click the desired Authorization Server name, usually “default”
Copy the “Metadata URI” value and send it to the PDC team
Click the “Access Policies” tab
Click “Add New Access Policy”
Set “Name” to PDC
Set “Description” to Allow users to authenticate to PDC
Set “Assign to” to The following clients:
Type P in the input box and then pick the “PDC” client created above
Click “Create Policy”
Under the new PDC policy, click “Add rule”
Set the “Rule Name” to Issue tokens to users authenticating to PDC
Reduce the token lifetimes such as to 5 minutes (access) and 90 minutes
Click “Create rule”.

Jump to Keycloak configuration

Okta Configuration using SAML

Save the current PDC keys in a PEM file

Visit the PDC Keycloak SAML configuration URL, similar to
https://example.org/realms/pdc/protocol/saml/descriptor
Within the XML document presented, copy and paste each PEM-encoded value
under “<md:KeyDescriptor use=‘signing’>…ds:X509Certificate”, similar to
MIIC...=, into a single (new) text file.
Surround each of the values from above with PEM headers and footers, namely
-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, each on their
own lines.
Line-wrap each of the values from above at 64 characters, according to
https://www.rfc-editor.org/rfc/rfc7468.html#page-5
Save the new file with a .crt extension, such as pdc_signing_keys.crt.

This file will be used below to configure signature validation. When using SAML
with Okta, there is no option to dynamically fetch these keys. So when PDC keys
are updated, the integration will not work until re-uploading the PDC keys. Thus
OIDC is preferred) when
using Okta.

Configure Okta App Integration

Log in to the admin area to Start a SAML App Integration (these steps follow
https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm
)
On the left nav bar, visit “Applications” -> “Applications”
Click “Create App Integration”
Click “SAML 2.0”
Click “Next”
Set “App Name” to Philanthropy Data Commons
If you wish to add a logo, one may be found on the PDC website
Check “Do not display application icon to users” under “App visibility” to
avoid erroneous IdP-initiated login attempts (because users begin the login
flow from PDC Apps and not from the Okta IdP)
Click “Next”
Paste the Single sign-on URL endpoint provided by the PDC team, similar to
https://example.org/realms/pdc/broker/foundation-okta-saml/endpoint
into Okta’s “Single sign-on URL”
Paste the “SP Entity ID URL” provided by the PDC team, similar to
https://example.org/realms/pdc into Okta’s “Audience URI (SP Entity ID)”
field
Set the “Name ID format” to EmailAddress
Set the “Application username” to Email
Expand “Show Advanced Settings”
Ensure both “Response” and “Assertion Signature” are Signed
Add a “Signature Certificate” PEM file by clicking “Browse files…”,
created [above](#Save the current PDC keys in a PEM file)
Add Attribute Statements (case sensitive, use the dropdown for each Value):
- Map firstName, Basic to user.firstName
- Map lastName, Basic to user.lastName
Click “Next”
Click “Finish”
Send Okta’s SAML “Metadata URL” value to the PDC team.

The PDC team will use this URL to configure an Identity Provider (IdP) within
PDC Keycloak and link it to a PDC Keycloak organization such that when users log
into PDC they will be redirected to their canonical IdP based on the domain name
in the email address. For example, entering “[email protected]” should
redirect the user to Okta. Okta
configuration
will determine whether a myfoundation user can log into the PDC. If
“[email protected]” has been assigned in Okta, then the Okta-configured
login procedure will be used for authentication, and if successful, the user
will be redirected to PDC Keycloak and be granted a valid PDC session.

Keycloak Configuration

Configure the PDC realm to use organizations and set up an organization.

See also this Keycloak Documentation:
https://www.keycloak.org/docs/26.2.5/server_admin/index.html#_managing_organizations

In the PDC realm, go to “Realm Settings”
Set “Organizations” to On (if not already enabled)
Set “Admin Permissions” to On
Click “Save”
Visit “Organizations”
Click “Create Organization” (if not already present):
- Set “Name” to the long name of the organization, e.g. My Foundation
- Set “Alias” to a short name of the organization, e.g. myfoundation
- Set “Domain” to the organization’s domain name, e.g. myfoundation.org
- Optionally set “Redirect URL” to the API documentation URL
Click “Save”.

Continue below for Okta via OIDC, or click here for Okta via SAML

PDC Keycloak configuration with Okta via OIDC

Add an OIDC Identity Provider to the PDC Realm.

See also this Keycloak documentation:
https://www.keycloak.org/docs/26.2.5/server_admin/index.html#_identity_broker_oidc

Visit “Identity Providers”
Click “Add Provider” of type “OpenID Connect v1.0.” If no existing providers
are present such that “Add Identity Provider” is not available, click “OpenID
Connect v1.0” under “User defined”
Set the “Alias” to the descriptive, simple, unique alias named above, e.g.
foundation-okta-oidc, Important: this alias sets the broker or
“Single Sign-on URL” used by Okta for integration and therefore must match
the “Single Sign-on URL” configured in Okta
Set the “Display name” to describe the organization that is herein linked
Under “OpenID Connect Settings” leave “Use discover endpoint” On
Set “Discovery endpoint” to the “Metadata URI” from Okta, similar to
https://example.org/oauth2/default/.well-known/oauth-authorization-server
Set “Client authentication” to JWT signed with private key
Set “Client ID” to the “Client ID” from Okta, similar to
0oatc6chn9IXY0389697
Leave “Client Secret” blank (it is not required due to using a keypair)
Leave “Client assertion signature algorithm” to Algorithm not specified
Leave “Client assertion audience” blank
Leave “Add X.509 Headers to the JWT” Off
Click “Add”
Under “OpenID Connect Settings”, ensure “Validate Signatures” is On
Set “Use PKCE” to On
Set “PKCE Method” to S256
Expand “Advanced”
Set “Pass login_hint” to On
Set “Scopes” to openid profile email
Set “Trust Email” to On
Set “Hide on login page” to On
Set “Sync mode” to Force
Click “Save”
Click the “Mappers” tab
Click “Add mapper”
Set “Name” to Import First Name From Profile Claim
Set “Mapper type” to Attribute Importer (from the dropdown)
Set “Claim” to profile
Set “User Attribute Name” to firstName (from the dropdown)
Click “Save”
Click “Provider details” near the top to go back to the “Mappers” tab
Click “Add mapper”
Set “Name” to Import Last Name From Profile Claim
Set “Mapper type” to Attribute Importer (from the dropdown)
Set “Claim” to profile
Set “User Attribute Name” to lastName (from the dropdown)
Click “Save”
Click “Provider details” near the top to go back to the “Mappers” tab
Click “Add mapper”
Set “Name” to Import Email Address From Email Claim
Set “Mapper type” to Attribute Importer (from the dropdown)
Set “Claim” to email
Set “User Attribute Name” to email (from the dropdown)
Click “Save”.

Link the newly added IdP to its corresponding organization.

Visit “Organizations”
Open the organization
Click the “Identity Providers” tab
Click “Link identity provider”
Select the IdP (created above) from the “Identity provider” dropdown menu
Select the organization’s domain name from the “Domain” dropdown menu
Keep “Hide on login page” set to On
Set “Redirect when email domain matches” to On
Click “Save”.

Test the integration

PDC Keycloak Configuration with Okta via SAML

Add a SAML Identity Provider to the PDC Realm.

See also this Keycloak documentation:
https://www.keycloak.org/docs/26.2.5/server_admin/index.html#_client-saml-configuration

Visit “Identity Providers”
Click “Add Identity Provider” of type “SAML v2.0.” If none are present such
that “Add Identity Provider” is not available, click “SAML v2.0” under “User
defined”
Set the “Alias” to the descriptive, simple, unique alias named above, e.g.
foundation-okta-saml, Important: this alias sets the broker or
“Single Sign-on URL” used by Okta for integration and therefore must match
the “Single Sign-on URL” configured in Okta
Set the “SAML entity descriptor” to the URL sent from the person who
configured Okta. In Okta this is called the “Metadata URL”
Verify that the “NameID policy format” is Email (if not, contact the person
who configured Okta to correct the Okta configuration, refer to Okta’s step 11)
Set the “Principal type” to Subject NameID
Set “Want AuthnRequests signed” to On
Set “Want Assertions signed” to On
Set “Validate Signatures” to On
Set “Sign service provider metadata” to On
Set “Pass subject” to On
Set “Hide on login page” to On
Set “Sync mode” to Force
Click “Save”
Click the “Mappers” tab on the Identity Provider
Add a map from firstName to firstName:
- Click “Add mapper”
- Set “Name” to Import First Name
- Leave “Sync mode override” as Inherit
- Select Attribute Importer from the “Mapper type” dropdown menu
- Set “Attribute Name” to firstName Important: this attribute name
  must match a “Name” set in Okta “Attribute Statements (optional)” for the
  import to work
- Leave “Name Format” as ATTRIBUTE_FORMAT_BASIC
- Select firstName from the “User Attribute Name” dropdown
- Click “Save”
Add a map from lastName to lastName:
- Click “Add mapper”
- Set “Name” to Import Last Name
- Leave “Sync mode override” as Inherit
- Select Attribute Importer from the “Mapper type” dropdown menu
- Set “Attribute Name” to lastName Important: this attribute name must
  match a “Name” set in Okta “Attribute Statements (optional)” for the
  import to work
- Leave “Name Format” as ATTRIBUTE_FORMAT_BASIC
- Select lastName from the “User Attribute Name” dropdown
- Click “Save”.

Link the newly added IdP to its corresponding organization.

Visit “Organizations”
Open the organization
Click the “Identity Providers” tab
Click “Link identity provider”
Select the IdP (created above) from the “Identity provider” dropdown menu
Select the organization’s domain name from the “Domain” dropdown menu
Keep “Hide on login page” set to On
Set “Redirect when email domain matches” to On
Click “Save”.

Test the integration