myHawaii OIDC & SAML Integration Guide

Introduction

This guide provides step-by-step instructions for integrating your application with myHawaii using OpenID Connect (OIDC) or Security Assertion Markup Language (SAML). These authentication protocols enable secure user authentication and Single Sign-On (SSO) capabilities.

---

1. Prerequisites

Before proceeding with the integration, ensure you have:

• Administrative access to the myHawaii identity platform
• A registered application in myHawaii
• Client credentials for OIDC (Client ID & Secret) or a metadata URL for SAML
• A valid HTTPS-enabled environment
• Basic knowledge of authentication protocols (OIDC/SAML)

---

2. OIDC Integration with myHawaii

2.1 Registering an OIDC Client

1. Log in to the myHawaii admin console.
2. Navigate to Applications > OAuth 2.0 Clients.
3. Click New Client and provide a unique client name.
4. Configure the following:
   • Client ID: Unique identifier for your application
   • Client Secret: Secure secret key for authentication
   • Redirect URIs: Callback URLs where the authorization response will be sent
   • Scopes: Define required scopes (e.g., openid, profile, email)
5. Save the client configuration.

2.2 Implementing OIDC Authentication

Use the following endpoints in your authentication flow:

• Authorization Endpoint: {MYHAWAII_HOST}/oauth2/authorize
• Token Endpoint: {MYHAWAII_HOST}/oauth2/access_token
• UserInfo Endpoint: {MYHAWAII_HOST}/oauth2/userinfo

OIDC Authentication Flow

1. Redirect users to the Authorization Endpoint with parameters:https://{MYHAWAII_HOST}/oauth2/authorize? response_type=code& client_id={CLIENT_ID}& redirect_uri={REDIRECT_URI}& scope=openid%20profile%20email& state={RANDOM_STRING}
2. Exchange the authorization code for an access token:POST {MYHAWAII_HOST}/oauth2/access_token Content-Type: application/x-www-form-urlencoded client_id={CLIENT_ID}& client_secret={CLIENT_SECRET}& grant_type=authorization_code& redirect_uri={REDIRECT_URI}& code={AUTHORIZATION_CODE}
3. Use the access token to retrieve user information from the UserInfo Endpoint.

---

3. SAML Integration with myHawaii

3.1 Configuring myHawaii as a SAML Identity Provider (IdP)

1. Log in to the myHawaii admin console.
2. Navigate to Federation > Entity Providers.
3. Click New SAML2 IDP and configure the following:
   • Entity ID: Unique identifier for the IdP
   • Assertion Signing Certificate: Upload a signing certificate for secure assertions
   • Single Sign-On (SSO) URL: Define the SAML assertion endpoint
   • Attribute Mapping: Map user attributes (e.g., email, givenName, sn)
4. Save and activate the IdP configuration.

3.2 Configuring the Service Provider (SP)

1. Obtain your Service Provider metadata file or manually configure:
   • SP Entity ID
   • ACS (Assertion Consumer Service) URL
   • NameID Format (e.g., email address, persistent)
2. Import the SP metadata into myHawaii:
   • Navigate to Federation > Entity Providers.
   • Click New SAML2 SP and upload the metadata file.
3. Configure SSO Bindings:
   • HTTP-Redirect for authentication requests
   • HTTP-POST for assertion responses
4. Save the configuration and establish the trust relationship.

3.3 Implementing SAML Authentication Flow

1. The SP redirects users to the myHawaii SAML SSO URL.
2. Users authenticate with myHawaii.
3. myHawaii generates a SAML Assertion and sends it to the SP’s ACS URL.
4. The SP validates the assertion and grants access.

---

4. Testing & Troubleshooting

4.1 Testing OIDC Integration

• Use Postman or a similar tool to request an access token.
• Verify the ID Token payload using jwt.io.
• Check the UserInfo Endpoint response.

4.2 Testing SAML Integration

• Use SAML Tracer (browser extension) to capture SAML requests.
• Verify assertions using an online SAML Decoder.
• Review myHawaii logs for authentication errors.

4.3 Common Issues & Fixes

Issue	Cause	Solution
Invalid redirect URI	Mismatched callback URL	Ensure the registered Redirect URI matches the request
Expired Token	Token TTL exceeded	Refresh the token or adjust expiration settings
SAML Assertion Rejected	Invalid certificate or signature	Verify the IdP signing certificate and trust settings

---

5. Conclusion

By integrating your application with OIDC or SAML, you can achieve secure, seamless authentication while maintaining compliance with modern identity management standards. Ensure ongoing monitoring, logging, and security updates to maintain a robust authentication flow.