Single Sign on Configuration

The GraphGrid dashboard supports Single Sign On (SSO) using SAML 2.0. All testing has been done with Okta, and documentation will be tailored towards Okta, though other SAML 2.0 Identity Providers (IdPs) should work.

note

Before starting this process, please configure SSL for your installation. See here for more info.

Okta Setup

In your Okta admin console, start by creating a new SAML 2.0 integration. After filling in the app name, and optionally uploading a logo, you can enter the following SAML Settings. {{baseURL}} should be substituted with your domain name or IP address (including http/https) like https://dev.graphgrid.com.

Field	Value
Single sign on URL	{{baseURL}}/1.0/security/saml/SSO
Audience URI (SP Entity ID)	{{baseURL}}/1.0/security/saml/metadata
Default RelayState	{{baseURL}}/login
Name ID format	EmailAddress
Application username	Okta username

Under the Attribute Statements section, add the following attributes. The Name formats can be Unspecified.

Name	Value
firstName	user.firstName
lastName	user.lastName
applicationName	graphgrid

Feel free to customize the applicationName attribute value, but remember to keep it consistent in future steps.

After customizing everything, go ahead and hit next, and follow the instructions from Okta until the app is created. Next, under the Sign On tab, find the "Identity Provider metadata" link. You will need this metadata URL in an upcoming step.

GraphGrid Setup

In order to use SSO, several configuration values need to be modified. See here for instructions on using the Config API to set configuration values. All values should be set for the docker environment (for a packaged deployment), under the security service, and with the appropriate version number for the branch (like 2.0.x). The base URL for your requests should be /1.0/config/updateConfigValue/security/docker/2.0.x. Remember to customize URLs to match your environment.

Please note that spring.okta.hostName should not have a leading http:// or https:// since that gets added using the value from spring.security.saml.protocol. Additionally, be aware of trailing slashes. During SAML verification, URLs must match up exactly. If you run into any errors, the security container logs can be quite helpful.

Parameter Key	Parameter Value
spring.okta.enabled	true
spring.okta.hostName	dev-package.graphgrid.com
spring.okta.password	Use a secure randomly generated password
spring.security.saml.cookieDomain	.graphgrid.com

note

Once the configuration parameters have been set, restart the Security service.

It is important to keep spring.okta.password secret, since it will be assigned as a backup for all SSO accounts. If you need to test without SSL, set spring.security.saml.protocol to http.

Finally, using an appropriate Org grn from the graph, and the metadata URL from Okta, create the SSO account integration. The GraphGrid security service will dynamically import all necessary SAML data from the metadata URL. You can optionally pass a redirectUrl property to redirect users after logout. Make sure applicationName matches up with what was entered into Okta under the Attribute Statements section.

curl --location --request POST "${API_BASE}/1.0/security/ssoaccount/new" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--data-raw '{
  "applicationName": "graphgrid",
  "type": "okta",
  "metadataUrl": "https://dev-21817789.okta.com/app/exk...5d6/sso/saml/metadata",
  "orgGrn": "grn:gg:org:wFLbDOhkrl979rdc5mv5oc8l66oMzOx1fTfvWo2RpBzy"
}'

You should now be able to assign the SAML application to users in Okta and have them authenticate. When they first authenticate, a User node will be created for them on the graph, and a corresponding user will be created in LDAP.