SSO
- Print
- PDF
SSO
- Print
- PDF
Article Summary
Share feedback
Thanks for sharing your feedback!
Available in Classic and VPC
SSO (Single Sign On) connection means an integrated login connection which gives you access to both WORKBOX and client company with one ID. WORKBOX basically supports SSO with SP (Service Provider) method. Developers's SSO supports both OAuth 2.0 and SAML (Security Assertion Markup Language) 2.0. Configuration method slightly varies, depending on how the user sets the connection.
Shared procedure of connecting SSO
No matter which of the two method is chosen, there is a shared procedure to follow in order to set the connection. The following explains the shared procedure.
- From Services > Business Applications > WORKBOX, go to Developers, and select Set SSO.
- Click the selectable item and change it to ON.
- Select and set the connection item you want from OAuth 2.0 and SAML 2.0.
- OAuth 2.0-based SSO: Refer to how OAuth 2.0-based SSO works and how to configure it
- SAML based SSO: Refer to how SAML based SSO works and how to configure it
- Click the [Apply] button.
OAuth 2.0-based SSO
The way OAuth 2.0-based SSO works and how to implement it is as follows.
① Use WORKBOX
The user connects with URL from a web browser, or runs the WORKBOX app to use WORKBOX.
② Request to issue authorization code
If not logged in to WORKBOX, then the request to issue an authorization code is sent to the client company's authentication system.
③ Run login page (if not logged in to the client company)
If not logged in to the client company system, then the self-made login page is provided to the user.
④ Enter ID/password
The user enters ID/password according to the client company's login policy.
⑤ Authorization code issued after the client company authentication
The client company system authentication is carried out with the ID/password and an authorization code is issued. If the user is already logged into the client company system, then Steps 3 and 4 are omitted and an authorization code is immediately issued.
An authorization code must be single-use only code that is used to return the access token and is eliminated.
⑥ Return (redirect) authorization code
The authorization code is redirected to redirect_uri of WORKBOX authentication system among the requests received when the authorization code issuance requests were initially made.
⑦ Request access token with the authorization code
With the authorization code as the parameter, a request for access token is made to the client company's authentication system.
⑧ Return access token
The client company's authentication system validates the authorization code, and issues and returns an access token.
⑨ Request user information with access token
With the access token as the parameter, a request for user information is made to the client company's authentication system.
⑩ Return user information
The client company's authentication system validates the access token, and returns the user's login email information.
⑪ Issue WORKBOX authentication token
WORKBOX authentication system issues an authentication token for WORKBOX, based on the user information.
Step 1: Web Login URL
This is a page for the user to enter ID/password to log in to WORKBOX web service. You can create the log in page to fit your company's needs.
After processing the client company login, issue an authorization code and return to redirect_uri.
Request URL
https://ClientCompanyDomain/ClientCompanyLoginPage
Only Port 443 can be used according to the WORKBOX's infrastructure security policy.
Register the request URL made to SSO settings' Web Login URL, under Developers in the NAVER Cloud Platform console.
HTTP Method
GET
Request
| Parameter | Type | Requirement status | Explanation |
|---|---|---|---|
| response_type | String | Y | Classification value for the authentication process, specifies which format of result value is to be received. A fixed string "code" is always used. |
| client_id | String | Y | Client ID value registered in the NAVER Cloud Platform console's Developers |
| redirect_uri | String | Y | URL to return the authorization code after the authentication is done, and is URL encoded |
| state | String | Y | Unique value randomly created for CSRF (Cross-site Request Forgery) (included in the URL when returning the authorization code, and the state value is sent as parameter.) |
| loginId | String | N | Login ID entered by user |
Step 2: Issue authorization code
After the client company's SSO system authenticates and processes what is required for SSO, it issues an authorization code and redirects to WORKBOX authentication system.
Request URL
URL is the redirect_uri parameter value sent from WORKBOX authentication system when it requested the login page.
E.g., https://WORKBOXAuthenticationSystemURL/authorizationURL
URL is a value that can change anytime, depending on user environment and WORKBOX policy, the URL received to redirect_uri must be used.
HTTP Method
GET/POST
Request
| Parameter | Type | Requirement status | Explanation |
|---|---|---|---|
| code | String | Y (Success) | A single-use only code that is used to issue authorization code or access token |
| state | String | Y (Success) | Authentication value on the client side used to prevent CSRF, and is URL encoded (state value sent to redirect_uri parameter) |
| error | String | Y (Failure) | Error code returned in case of failure |
| error_description | String | Y (Failure) | Explanation of the error code returned in case of failure |
Step 3: Issue access token API
The client company's SSO system validates the authorization code, and issues and returns an access token.
Request URL
https://ClientCompanyDomain/accessToken
Only Port 443 can be used according to the WORKBOX's infrastructure security policy. Register the request URL made to SSO settings' Access Token Return API, under Developers in the NAVER Cloud Platform console.
HTTP Method
POST
Request
| Parameter | Type | Requirement status | Explanation |
|---|---|---|---|
| grant_type | String | Y | Classification value for the authentication process, specifies which format of result value is to be received. A fixed string "authorization_code" is always used |
| client_id | String | Y | Client ID value registered in the NAVER Cloud Platform console's Developers |
| client_secret | String | Y | Client secret value registered in the NAVER Cloud Platform console's Developers |
| code | String | Y | Authorization Code |
| state | String | N | Authentication value on the client side used to prevent CSRF, is URL encoded |
Response
| Property | Type | Requirement status | Explanation |
|---|---|---|---|
| access_token | String | Y (When successful) | Access Token |
| token_type | String | Y (When successful) | Access token's type. Fixed as "Bearer" |
| expires_in | String | Y (When successful) | Access token's valid time (seconds). Actual application's login maintained time |
| error | String | Y (When unsuccessful) | Error code returned in case of failure |
| error_description | String | Y (When unsuccessful) | Explanation of the error code returned in case of failure |
Step 4: Return user information API
The client company's SSO system validates the access token, and returns the user information.
Request URL
https://ClientCompanyDomain/UserInformation
Only Port 443 can be used according to the WORKBOX's infrastructure security policy.
Register the request URL made to SSO settings' User Info Return API, under Developers in the NAVER Cloud Platform console.
HTTP Method
POST
Request
| Parameter | Type | Requirement status | Explanation |
|---|---|---|---|
| client_id | String | Y | Client ID value registered in the NAVER Cloud Platform console's Developers |
| client_secret | String | Y | Client secret value registered in the NAVER Cloud Platform console's Developers |
| access_token | String | Y | Access Token |
Response
| Property | Type | Requirement status | Explanation |
|---|---|---|---|
| email_id | String | Y (When successful) | Member's login ID (work email) |
| error | String | Y (When unsuccessful) | Error code returned in case of failure |
| error_description | String | Y (When unsuccessful) | Explanation of the error code returned in case of failure |
SAML based SSO
The way SAML (Security Assertion Markup Language) 2.0-based SSO works and how to implement it is as follows.
① Use WORKBOX
The user connects with URL from a web browser, or runs the WORKBOX app to use WORKBOX.
② Create SAML request and redirect
If not logged in to WORKBOX, then a SAML request is created and sent to the client company's authentication system.
③ Run login page (if not logged in to the client company) after validating SAML request
The client company authentication system checks if the SAML request is valid, and provides the self-made login page to the user if they are not logged in to the client company system
④ Enter ID/password
The user enters ID/password according to the client company's login policy.
⑤ Create SAML response after client company authentication
The client company system authentication is carried out with the ID/password and a SAML response is created.
If the user is already logged into the client company system, then the login page is omitted and a SAML response is immediately created.
SAML response needs to be electronically signed with the pre-registered certificate on WORKBOX.
⑥ Send (redirect) SAML response
Send the SAML response to the SAML request's ACS URL sent from WORKBOX.
⑦ Issue WORKBOX authentication token after confirming SAML response
The client company validates the SAML response with the pre-registered certificate to authenticate and confirm user information, and then issue an authentication token for WORKBOX.
Step 1: SAML web login page
This is a page for the user to enter ID/password to log in to WORKBOX web service. You can create the log in page to fit your company's needs.
After validating the SAML request and processing the client company login, create the SAML response and return to ACS URL.
Request URL
https://ClientCompanyDomain/ClientCompanyLoginPage
Only Port 80 or 443 can be used according to the WORKBOX's infrastructure security policy.
Register the request URL made to SSO settings' Web Login URL, under Developers in the NAVER Cloud Platform console.
HTTP Method
GET
Request
| Parameter | Type | Requirement status | Explanation |
|---|---|---|---|
| SAMLRequest | String | Y | String according to the SAML 2.0 request detail (Encoded value using Deflate + Base64) |
| RelayState | String | Y | URL to retry in case the authentication fails |
Step 2: Validate SAML request
A SAML request is encoded using Deflate + Base64.
SAML request details
<?xml version="1.0" encoding="UTF-8"?>
<saml2p:AuthnRequest
xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
AssertionConsumerServiceURL="{ACS URL}"
ID="{ID issued by WORKBOX authentication system}"
IssueInstant="{Request creation date and time}"
ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
ProviderName="ncloudworkbox.com"
Version="2.0">
<saml2:Issuer
xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">ncloudworkbox.com</saml2:Issuer>
<saml2p:NameIDPolicy Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"/>
</saml2p:AuthnRequest>
SAML request's items are as follows.
| Item | Explanation |
|---|---|
| AuthnRequest AssertionConsumerServiceURL | ACS URL in short, it is the URL that relays a SAML response |
| AuthnRequest ID | ID issued by WORKBOX authentication system, is used when creating a SAML response |
| AuthnRequest IssueInstant | SAML request creation date and time |
| AuthnRequest ProtocolBinding | It is sent as HTTP-POST, so a SAML response must be sent using the POST method |
| AuthnRequest ProviderName | Name of a service provider, sending it as ncloudworkbox.com |
| Issuer | The ID, issued by the service provider, is used when creating a SAML response |
SAML Request Example
<?xml version="1.0" encoding="UTF-8"?>
<saml2p:AuthnRequest
xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
AssertionConsumerServiceURL="https://CompanyID.ncloudworkbox.com/...."
ID="bemkplgpdoemkhjmncgmbcdibglpngclfombpmed"
IssueInstant="2018-02-14T03:33:49.999Z"
ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
ProviderName="ncloudworkbox.com"
Version="2.0">
<saml2:Issuer
xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">ncloudworkbox.com</saml2:Issuer>
<saml2p:NameIDPolicy Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"/>
</saml2p:AuthnRequest>
Step 3: Register certificate for SAML response electronic signature
Register a certificate to be used when electronically signing a SAML response. WORKBOX uses this certificate to validate a SAML response received via ACS URL.
Register the certificate to Certificate File in SSO settings under Developers in the NAVER Cloud Platform console.
Register certificate for electronic signature, based on SAML 2.0
Log out
WORKBOX logout and client company logout are explained separately.
WORKBOX logout
Used when logging out from WORKBOX after logging out from the client company's system.
When WORKBOX receives a logout request, it logs out the logged-in WORKBOX account and redirects it to the redirect_uri it has received.
redirect_uri is managed with white_url, so it should be registered to Logout Redirection Domain in the NAVER Cloud Platform console Developers's SSO settings.
Request URL
https://CompanyID.ncloudworkbox.com/authn/logoutProcess
HTTP Method
GET/POST
Request
| Parameter | Type | Requirement status | Explanation |
|---|---|---|---|
| redirect_uri | String | Y | It is URL encoded as the URL to be redirected after logging out from WORKBOX |
Response
Redirect to redirect_uri.
Client company logout
Used when processing the logout from the client company's system after logging out from WORKBOX.
Request URL
https://ClientCompanyDomain/Logout
Only Port 443 can be used according to the WORKBOX's infrastructure security policy.
Register the request URL made to SSO settings' Logout URL, under Developers in the NAVER Cloud Platform console.
HTTP Method
GET
Request
| Parameter | Type | Requirement status | Explanation |
|---|---|---|---|
| redirect_uri | String | N | redirect_uri to redirect after the logout from the client company's system is processed. URL encoded |
After SSO connection is completed
When SSO connection is complete, WORKBOX login is available with the login information of the existing enterprise information system. This makes it convenient to manage login information.
Was this article helpful?