h1. Purpose
This tutorial demonstrates how to set up QuickBuild to authenticate via [Okta|https://okta.com] using SAML protocol
h1. Assumptions
# QuickBuild is accessed via https://build.example.com
h1. Steps
# Login to your organization account at Okta, and switch to Classic UI from _Developer Console_
!okta-classic-ui.png!
# Add appropriate QuickBuild groups, for instance qb.developers and qb.testers, and add your current Okta account into these groups
!okta-groups.png!
# Create new application in Okta, with platform being _Web_ and sign in method being _SAML 2.0_:
!okta-create-new-app.png!
# Fill in general setting of the application, and click next:
!create-app-general-setting.png!
# Fill in SAML settings as below and click next:
!okta-saml-setting.png!
# Select appropriate options in feedback page and click finish:
!okta-feedback.png!
# Okta will bring you to the _Sign On_ tab after clicking finish button above. From here, click the _Identity Provider Metadata_ link to show the content:
!okta-idp.png!
# Copy the metadata XML into clipboard
!copy-idp-metadata.png!
# Navigate to _Assignments_ tab and make sure you've been assigned to the application:
!app-assignment.png!
# Now login to QuickBuild, navigate to page _Administration/Security Setting_ and select _SSO via SAML2_ as _SSO Provider_. Paste the copied metadata from above step into field _IdP Metadata_
# Run below commands to generate SP private key and self-signed SP certificate:
{code}
openssl req -x509 -nodes -days 365 -newkey rsa:4096 -keyout sp-key.pem -out sp-cert.crt
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in sp-key.pem -out sp-key-pkcs8.pem
{code}
Copy content of file _sp-key-pkcs8.pem_ into field _SP Private Key_, and content of file _sp-cert.crt_ into field _SP Cert_
{note}For Okta SAML integration, SP cert is actually not used as it does not verify authentication request signature. However other SAML integrations may require you to upload the SP cert to verify the signature.{note}
# Specify _email_ for field _Email Attribute_, and _group_ for _Group Names Attribute_. Attributes specified here should be the same as you've specified at Okta side
# Specify a default group if necessary and save the setting
# Navigate to _Group Management_ page and define groups with same name as we've defined in Okta, and assign appropriate permissions:
!qb-groups.png!
# Navigate to page _Administration/System Setting_, and make sure property _Url to Access QuickBuild_ is specified as _https://build.example.com_
# Now logout and visit _https://build.example.com_ (make sure to visit the url specified in system setting), the sign in page should display a SSO login button
!sso-signin.png!
# Click this button and you will be taken to Okta site for authentication. If authenticated successfully, you will be logged into QuickBuild.
{note}You can still login to QuickBuild with normal user/password without clicking the SSO button{note}
This tutorial demonstrates how to set up QuickBuild to authenticate via [Okta|https://okta.com] using SAML protocol
h1. Assumptions
# QuickBuild is accessed via https://build.example.com
h1. Steps
# Login to your organization account at Okta, and switch to Classic UI from _Developer Console_
!okta-classic-ui.png!
# Add appropriate QuickBuild groups, for instance qb.developers and qb.testers, and add your current Okta account into these groups
!okta-groups.png!
# Create new application in Okta, with platform being _Web_ and sign in method being _SAML 2.0_:
!okta-create-new-app.png!
# Fill in general setting of the application, and click next:
!create-app-general-setting.png!
# Fill in SAML settings as below and click next:
!okta-saml-setting.png!
# Select appropriate options in feedback page and click finish:
!okta-feedback.png!
# Okta will bring you to the _Sign On_ tab after clicking finish button above. From here, click the _Identity Provider Metadata_ link to show the content:
!okta-idp.png!
# Copy the metadata XML into clipboard
!copy-idp-metadata.png!
# Navigate to _Assignments_ tab and make sure you've been assigned to the application:
!app-assignment.png!
# Now login to QuickBuild, navigate to page _Administration/Security Setting_ and select _SSO via SAML2_ as _SSO Provider_. Paste the copied metadata from above step into field _IdP Metadata_
# Run below commands to generate SP private key and self-signed SP certificate:
{code}
openssl req -x509 -nodes -days 365 -newkey rsa:4096 -keyout sp-key.pem -out sp-cert.crt
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in sp-key.pem -out sp-key-pkcs8.pem
{code}
Copy content of file _sp-key-pkcs8.pem_ into field _SP Private Key_, and content of file _sp-cert.crt_ into field _SP Cert_
{note}For Okta SAML integration, SP cert is actually not used as it does not verify authentication request signature. However other SAML integrations may require you to upload the SP cert to verify the signature.{note}
# Specify _email_ for field _Email Attribute_, and _group_ for _Group Names Attribute_. Attributes specified here should be the same as you've specified at Okta side
# Specify a default group if necessary and save the setting
# Navigate to _Group Management_ page and define groups with same name as we've defined in Okta, and assign appropriate permissions:
!qb-groups.png!
# Navigate to page _Administration/System Setting_, and make sure property _Url to Access QuickBuild_ is specified as _https://build.example.com_
# Now logout and visit _https://build.example.com_ (make sure to visit the url specified in system setting), the sign in page should display a SSO login button
!sso-signin.png!
# Click this button and you will be taken to Okta site for authentication. If authenticated successfully, you will be logged into QuickBuild.
{note}You can still login to QuickBuild with normal user/password without clicking the SSO button{note}