CIAM 1.5

CIAM Phase 1.5 prepares for Phase 2 and aligns with OAuth 2.0 Security Best Current Practice by deprecating Password Grant in favor of Authorization Code flow using PKCE for Native Apps.

This will then allow our customers to use their own Identity Providers for Single-Sign On in Phase2. 

Overview

Phase 1.5 begins our improvement of security by moving team selection (currently implemented in different ways in every application) into the OAuth2 login flow.

Here's what it looks like for our users:

Username and Password >>>	Team  Selection >>>	Consent

This improves our life in two ways:

• we implement team-selection once in a standard way;
• our tokens are more narrowly scoped, reducing the risk of them being used in "bad" ways

Accordingly, you will need to make the following changes:

• CIAM 1.5 JWT tokens provide both a proven identity and a user-chosen team.
  • This means  you will no longer have to manage team selection.
  • So your application will need to remove any logic around team selection. 

• CIAM 1.5 is designed to use the new Topcon Brand Bar (as the old brand bar was replete with team selection etc, which is no longer necessary).
  • This component, given appropriate configuration, takes care of
    
    • your application's log-out process
    • links to changing teams and managing user data
    • providing an application palette (still in development)
  • So your application can remove any logic it uses to provide these features.
• If you are using Password Grant, you will need to deprecate that and use the Native App flow

With these changes, OAuth2 authorization results in the issuance of a token which can be used as a Bearer Token by the TRAPI REST API for a single team.

Preparing for Phase 1.5

Before migrating to use Phase1.5 you need to be aware of the following:

• You will need to have a PingFederate client created; see section .
• Your application will obtain access tokens using the Authorization Code flow.
  • Authorization requests will need to use a scope of topcon.ciam.phase.1.5 
  • Authorization requests will need to provide a redirect-uri. Currently this is managed by TRAPI. While this increases the burden on callers, it means that you can have multiple redirect-uris defined.
• Phase 1.5 tokens provide TRAPI with a username and team.
  • the user will choose a team as part of the authentication process. See section .
  • the default team is not used and will be removed in a future phase once all users are using CIAM.

Creating an OAuth2 Client for Phase 1.5

In future we will have a self-service procedure for client creation but for the moment, please visit Topcon JIRA IT Service Desk and raise an IT Support ticket containing the following details:

Subject: Please create OAuth2 Client in PingFederate

Body:

Attention: James Picton-Warlow

Name: (name of your application)

Description: (description of your application)

Short Name: (unique name for the App Palette to use)

Phase:  1.5

Contacts:  (names and emails of the people to contact for support)

Redirects: (list of URIs for OAuth2 redirection process)

Alternatively you can use this link to send an email to itservicedesk@topcon.com .

Configuring OAuth in your application

The necessary endpoints can be found from the following well-known endpoints: **CLEANUP**

• QA: https://qa-token.auth.topcon.com/.well-known/openid-configuration

Tokens

Token fields

Phase 1.5 tokens are JWTs containing the following fields:

For example,

{
	"client_id": "8da9633e-6e1c-4292-a464-23e7ced0de29",
	"exp": 1698719430,
	"iss": "ping-qa",
	"jti": "bzrRX0HaebiO",
	"orgunit": "q6awkKO3q7elmpfWm5qmurF/qLWkpZuq",
	"scope": "openid topcon.ciam.phase.1.5",
	"sub": "e731d351-9515-4997-8f62-5bce2463d793",
	"username": "xxxxxx@yyyyyy.com"
}

Getting team information

Phase 1.5 tokens can only be used for one team, and contain obfuscated team data.

You can find the team from the TRAPI REST API:

Using TRAPI_HOST 

• (QA) https://api-qa.topcon.com
• (PROD) https://api.topcon.com

[
	{
		"id": "a2L1bxxxxxxxxxxEAM",
		"name": "XXX XXXXX XX",
		"role": "Admin",
		"isDealer": false,
		"isDefault": true
	}
]

Logging out

The following URLs will log out of Ping Fed/Ping One and return the user to the mytopcon front page:

• QA: https://qa-token.auth.topcon.com/idp/startSLO.ping
• Prod: https://token.auth.topcon.com/idp/startSLO.ping

This is our recommended and supported method of logging out. We intend to maintain these going forward such that they will log out of our systems. 

Examples

You can find some example code in our Best Practise page.