How to login with SSO

1. Overview

CostOS supports Single Sign-On (SSO) via:

• SAML v2.0

• OpenID Connect v1.0

This allows users to authenticate with their corporate identity provider (e.g., Azure AD, Okta, Keycloak, ADFS, Ping Federate) instead of using local CostOS credentials.

⚠️ Only users with the User Administrator role can configure authentication settings in CostOS.

2. Prerequisites

Before configuring SSO:

1. Log in to CostOS Web Interface or Workstation Client using an account with the User Administrator role.

2. Obtain necessary details from your Identity Provider (IdP):

   • For SAML 2.0: metadata URL, Entity ID, redirect URL

   • For OpenID Connect: discovery endpoint, client ID, and client secret

3. Ensure CostOS Server is reachable by the IdP via HTTPS.

4. Back up your existing authentication configuration.

5. Keep a local admin account enabled in case SSO misconfiguration prevents login.

3. Accessing Authentication Settings

1. Log in to CostOS Web Interface as an administrator.

2. Go to:
   Administration → Security → Authentication Settings

3. Select the Authentication method:

   • SAML v2

   • OpenID Connect v1.0

4. SAML v2.0 Configuration

4.1 Field-by-Field Description

💡 Note:
The Private Key and Certificate are not mandatory. CostOS automatically uses HTTPS to protect communication. Only configure them if your IdP requires message signing or encryption.

4.2 Certificate Management

• Click Recreate to generate a new key/certificate pair (valid for 1 year).

• You can export the certificate in several formats:

  • .cer – for metadata import to IdP

  • .jks – Java KeyStore (alias: default, password: changeit)

  • .pfx – PKCS#12 bundle (alias: default, password: changeit)

• Exported certificates are stored in the CostOS installation directory.

4.3 IdP Configuration Steps

In your Identity Provider (e.g., Keycloak, ADFS, Azure AD, Okta):

1. Create a new SAML application / service provider.

2. Enter:

   • Entity ID → same as Service Provider Entity ID

   • Assertion Consumer Service (ACS) → same as Redirect URI

3. Upload the CostOS certificate, if using message signing.

4. Set the NameID format to match CostOS usernames (usually username or email).

5. Assign users or groups who can access the application.

4.4 Save and Test

1. Click Save in CostOS.

2. Log out.

3. On the login screen, select your configured SAML method.

4. You should be redirected to your IdP login page.

5. Authenticate and confirm successful redirection back to CostOS.

5. OpenID Connect (OIDC) Configuration

5.1 Field-by-Field Description

💡 Note:
The “Username Claim” value must match the CostOS username field for the user to be identified correctly after authentication.

5.2 Identity Provider Configuration Steps

In your OpenID Connect provider (e.g., Keycloak, Azure AD, Okta):

1. Create a new OpenID client / application named CostOS.

2. Add a Redirect URI matching the one displayed in CostOS (/ces/openid-login).

3. Enable standard flows (authorization_code, refresh_token).

4. Copy the Client ID and Client Secret into CostOS.

5. Optionally configure the Username Claim mapping (e.g., preferred_username).

6. Assign the correct users or groups to the CostOS client.

5.3 Save and Test

1. Click Save in CostOS.

2. Log out and select the OpenID login option.

3. You should be redirected to your IdP for authentication.

4. After successful login, you will return to CostOS as an authenticated user.

6. Troubleshooting

7. Security Recommendations

• Always use HTTPS for all URLs.

• Restrict SSO configuration access to User Administrators.

• Rotate certificates and client secrets regularly (e.g., annually).

• Keep one local admin account enabled for emergency access.

• Audit SSO logins periodically to detect inactive or unauthorized users.

8. Example Configurations

9. Support

If you encounter configuration or login issues:

• Check the CostOS server logs (ces.log, auth.log) for SSO-related messages.

• Validate the IdP metadata or discovery URL in a browser.

• Contact CostOS Support at 📧 support@costos.example.com (replace with your actual contact address).