Select Page
by

Sagayaraj D

|
last updated on August 1, 2022
Share

Purpose

SAML SSO provides flexibility to login once against an Authentication source and maintain user session across multiple applications of an organization. It eliminiates the need to remember user credential for every individual system and avoids logging into them individually.

The scope of this guide is how to setup SAML authentication on Spinnaker using GSuite SAML app.

Pre-Requirements

We should be having the following items working/configured before configuring Spinnaker…
  • Spinnaker 1.16.2
  • GSuite with valid users
  • You should be Administrator on GSuite to configure SAML app

Configuring Spinnaker Authentication using GSuite SAML

To configure SAML authentication in Spinnaker, you need to
  • Add an application in GSuite SAML apps for Spinnaker, then
  • Configure Halyard using some of the settings from GSuite SAML application

Adding Spinnaker application in GSuite SAML

Note: You should be a GSuite Administrator to perform the steps under this section. Else you cannot configure SAML setup.
 
1. Login to your GSuite Admin console (admin.google.com), and go to Apps > SAML apps.

2. Click Add (or, + button) at the bottom right. This will bring up all SAML enabled Google apps. Ignore the list and Click ‘Set up my own custom app’ to add Spinnaker application.

3. On the next screen, there will be two options namely ‘Option 1’ and ‘Option 2’. You can configure your SAML using either one of the options. Go for the Option 2, and download the metadata file. Copy this file to your halyard machine.
 
 4. In the next screen, provide an application name ‘Spindd’. Description and the Logo file are optional but good to have.
 
5. Now setup the ACS URL (also called SSO URL) and Entity ID. The SSO URL here should be the “Gate URL + ‘/saml/SSO’ “. Entity ID here in SAML app should match with the Issuer ID in Spinnaker Halyard.
 
  • ACS URL: https://spindd.opsmx.com:30084/saml/SSO (Note the suffix)
  • Entity ID: Spindd.Dev

Note: The Name ID value here will be mapped as the User name on Spinnaker application. You can set it to Primary Email, First Name or Last Name as shown in the picture.

6. Next screen is about ‘Attribute Mapping’ between SAML app to actual Spinnaker app. This is not mandatory for authentication step, and can be edited later when configuring authorization.
 
7. Turn ON the app.
By default the new app that just got setup will be in disabled state.
 Turn it ON for everyone, so that Spinnaker can use the SAML.
 
 You now have completed the steps on GSuite SAML apps for Spinnaker. Now go to Spinnaker Halyard to configure Spinnaker.
 

Configuring Halyard to use GSuite SAML

Note: Perform the steps here in Halyard machine.

1. Create a SAML key store for Spinnaker

				
					KEYSTORE_PATH=/home/spinnaker/.hal/saml/saml.jks
keytool -genkey -v -keystore $KEYSTORE_PATH -alias saml -keyalg RSA -keysize 2048 -validity 10000
				
			

2. Configure Spinnaker to use SAML

				
					spinnaker@halyard-57f8d6f8dc-74xbp:~/.hal/saml$ cat vars.saml
KEYSTORE_PATH=/home/spinnaker/.hal/saml/saml.jks
KEYSTORE_PASSWORD=xxxxxx # Password entered in the step just above.
METADATA_PATH=/home/spinnaker/.hal/saml/GoogleIDPMetadata-opsmx.io.xml
SERVICE_ADDR_URL=https://spindd.opsmx.com:30084
ISSUER_ID=Spindd.Dev #This value should be same as Entity ID value entered in GSuite SAML setup screen.
spinnaker@halyard-57f8d6f8dc-74xbp:~/.hal/saml$ source vars.saml
spinnaker@halyard-57f8d6f8dc-74xbp:~/.hal/saml$ hal config security authn saml edit \
--keystore $KEYSTORE_PATH \
--keystore-alias saml \
--keystore-password $KEYSTORE_PASSWORD \
--metadata $METADATA_PATH \
--issuer-id $ISSUER_ID \
--service-address-url $SERVICE_ADDR_URL
				
			

3. Enable SAML authentication

				
					spinnaker@halyard-57f8d6f8dc-74xbp:~/.hal/saml$ hal config security authn saml enable
				
			

If any authentications other than SAML were enabled like oauth2, you should disable them. In my case oauth2 was enabled, I had to disable it.

				
					spinnaker@halyard-57f8d6f8dc-74xbp:~/.hal/saml$ hal config security authn oauth2 disable
				
			

4. Apply the changes

				
					spinnaker@halyard-57f8d6f8dc-74xbp:~/.hal/saml$ hal deploy apply
				
			
Once changes are applied, you can verify Spinnaker authentication. It should take you Google login page, should be able to authenticate to Spinnaker successfully. 

Optional: Attribute Mapping

After successful login to Spinnaker, checking the below URL can tell you of the attributes successfully mapped.

https:///auth/user
Our URL: https://spindd.opsmx.com:30084/auth/user
Page output is in Json, something like below
				
					{
    "email": "sagayaraj.d@opsmx.io",
    "username": "sagayaraj.d@opsmx.io",
    "firstName": null,
    "lastName": null,
    "roles": [],
    "allowedAccounts": [
        "k8s-qa-spin",
        "saga-azure-account"
    ],
    "enabled": true,
    "authorities": [],
    "accountNonExpired": true,
    "credentialsNonExpired": true,
    "accountNonLocked": true
}
				
			
By looking at the output above, we can understand that email and username are set; other attributes like firstName and lastName are not set. If we need them set, go and do ‘Attribute mapping’ in GSuite SAML app configuration.
 
Attribute Mapping
 
In GSuite SAML, go to _’Spindd’_ SAML application > ‘Attribute Mapping’ configuration.
Do the attributes mapping as here,
Name: firstName, Category: Basic Information, Attribute: First Name
Name: lastName, Category: Basic Information, Attribute: Last Name
 
Note: Here, ‘Name’ field value should match the actual Spinnaker attribute and the ‘Attribute’ field value is from the GSuite user’s attribute.
 
Now on Halyard, update the attribute mapping from GSuite to Spinnaker fields.
				
					spinnaker@halyard-57f8d6f8dc-74xbp:~/.hal/saml$ hal config security authn saml edit \
--user-attribute-mapping-first-name firstName \
--user-attribute-mapping-last-name lastName
# List of possible attributes we can associate are here. We can eliminate any of the attribute that is not required.
spinnaker@halyard-57f8d6f8dc-74xbp:~/.hal/saml$ hal config security authn saml edit \
--user-attribute-mapping-username userName \
--user-attribute-mapping-email email \
--user-attribute-mapping-first-name firstName \
--user-attribute-mapping-last-name lastName
--user-attribute-mapping-roles memberOf \
--user-attribute-mapping-roles-delimiter ,
				
			
Once Spinnaker has applied the changes, check our URL again: https://spindd.opsmx.com:30084/auth/user
Resultant json now shows that firstName and lastName are mapped.
				
					{
  "email": "sagayaraj.d@opsmx.io",
  "username": "sagayaraj.d@opsmx.io",
  "firstName": "Sagayaraj",
  "lastName": "David",
  "roles": [],
  "allowedAccounts": [
    "k8s-qa-spin",
    "saga-azure-account"
  ],
  "authorities": [],
  "enabled": true,
  "accountNonExpired": true,
  "credentialsNonExpired": true,
  "accountNonLocked": true
}
				
			
 Troubleshooting
If you are unable to login, your configuration changes could have gone wrong somewhere. Check if any of the following scenarios match your case, and apply the solution.

Problem 01: Following error appears immediately after accessing Spinnaker deck url

403. That’s an error. Error: app_not_configured_for_user Service is not configured for this user. Request Details That’s all we know.

Solution: Possibly the App is not turned ON in GSuite. Enable it

Problem 02: Following error appears immediately after entering username and password. 403. That’s an error. Error: app_not_configured_for_user Service is not configured for this user. Request Details That’s all we know.

Solution: The Issuer ID on Halyard configuration does not match with the Entity ID on GSuite SAML apps. Make sure they are configured with same value.

Problem 03: During Spinnaker authentication process, after entering username and password web page is looping back and forth continuously.

Solution: Most likely the the ACS URL in GSuite and SERVICE_ADDR_URL in Halyard are pointing to Gate URL only – https://spindd.opsmx.com:30084. Rember on Halyard it should be Gate URL and on GSuite, ACS URL should be ‘Gate URL + /saml/SSO’

Problem 04: 500. That’s an error. There was an error. Please try again later. That’s all we know.

Solution: Most likely the SAML app is GSuite is deleted by someone. Verify and re-configure SAML app in GSuite.

0 Comments

Submit a Comment

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.