So I recently had the challenge of setting up SAML authentication from Jumpcloud to an existing application that uses Keycloak (v18.x) as its authentication provider. As Keycloak can also be used as an identity provider the configuration can be a bit confusing.

Keep in mind this quick tutorial assumes that you already have an existing Keycloak client which you are using to authenticate your service. Details of building a client are outside the scope of these instructions.

So lets get into it...

Variables and Standards

The first thing we need to do is decide on some common variables and standards for this tutorial. Moving forward when referencing user defined variable we will wrap them in moustaches e.g. {{var_here}}

• iDpID: idp-jumpcloud-saml (ID Provider ID)
• BaseURL: keycloak.example.com (base url of your Keycloak instance)
• RealmName: myrealm (Keycloak realm name)
• RealmClient: myclient
• SPID: sp-jumpcloud-saml (Service Provider ID)
• AppID: mysaml (Display label of your Jumpcloud App)
• SPAppUrl: https://unogs.com

Configure Jumpcloud

• Login to the Jumpcloud admin interface
• Click on SSO
• Click the large green + button
• Click Custom SAML App (bottom of page)
• Fill out your display label with {{JDSID}}
• Fill in a description if you want
• Click on the SSO Tab
• fill in IdP Entity ID with {{iDpID}}
• fill in SP Entity ID with {{SPID}}
• fill in ACS URL: https://{{BaseURL}}/realms/{{RealmName}}/broker/{{iDpID}}/endpoint
• select SAMLSubjectNameID: as username

• select Signature Algorithm as RSA-SHA256
• fil in Login URL as https://{{BaseURL}}/realms/{{RealmName}}/protocol/openid-connect/auth?response_type=code&client_id={{RealmClient}}&scope=openid&redirect_uri={{SPAppURL}}&kc_idp_hint={{SPID}}
  • note: if you want to see your previous keycloak login screen remove: kc_idp_hint
• tick Sign Assertion
• fill in IDP URL with {{APPID}}
• Add the following User Attributes:
  • value email select email
  • value firstname select firstname
  • value lastname select lastname
• e.g.

• click activate
• click on your newly created APP
• click on the User Groups tab and select the group you want to give the above app access to.
• click on the SSO tab
• click Export Metadata, an xml called JumpCloud-saml.xml file will be saved locally

Configure Keycloak

Via the admin portal:

• click Identity Providers
• select Add Provider and select SAML v2.0
• change Alias to {{iDpID}}
• e.g.

• change Service Provider Entity ID to {{SPID}}
• scroll to bottom of the page, select Select File and choose JumpCloud-saml.xml
• click Import
• click Save
• e.g.

• go back into newly created provider and click the Mappers tab
• do the following for email, firstname and lastname
  • click create
  • give it a name
  • change Mapper type to attribute importer
  • fill in Attribute Name to type (email, firstname, lastname)
  • fill in Friendly Name to type (email, firstname, lastname)
  • select ATTRIBUTE_FORMAT_UNSPECIFIED
  • fill in User Attribute Name kctype (email,firstName,lastName)

Wrap UP

If everything went as planned, the above configuration should allow your users to click on a new app in their jumpcloud console and it will automatically login via your existing client. For new users this configuration should also automatically populate user details in the JWT.

If you have any questions or anything doesn't work as expected feel free to email me at admin@unogs.com