# Connect to OIDC identity source

Connect to OIDC identity source

# Step

[Connect OIDC identity source](#Connect-oidc-identity source)
- Step
- [Create an OIDC Provider at your OIDC provider] (#Create an -oidc-provider at your -oidc-service provider)
- [Create an OIDC IdP connection in the Authing console](#Create an -oidc-idp-connection in the -authing-console)
  - [Choose the connection mode that suits you] (#Select the connection mode that suits you)
- [Use Authing login form to test this connection](#Use -authing-login form to test this connection)
- [Use the API interface to test this connection](#Use -api-interface to test this connection)
  - POST start-interaction
  - [Initiate a login request to OIDC IdP] (#Initiate a login request to -oidc-idp-)
  - [Receive user information] (#Receive user information)
  - [Next Step] (#Next Step)

# Create an OIDC Provider at your OIDC service provider

You can choose any OIDC service provider. The specific creation differs depending on the service provider. Here we take the OIDC Provider of Authing as an example to create an OIDC Provider:

On the Applications- Application List page, click the Create button in the upper right corner to create an application. Make sure that the protocol type selected is OIDC:

After the creation is complete, you can see the App ID (ie clientId) and App Secret (ie clientSecret) of the OIDC application on the application details page, as well as the Issuer address:

These three items will be used later when Authing creates an OIDC IdP connection.

At the same time, please add https://core.authing.cn/connection/oidc/callback to the allowed callback link of your OIDC IdP:

# Create an OIDC IdP connection in the Authing console

On the Application Console> Connect Identity Source> Corporate Identity Source page, click the Create button in the upper right corner to create a new OIDC connection:

Examples of the following parameters are as follows:

Connection identifier: The unique identifier of the connection, which must be unique in the user pool.
Display Name: If set, the Authing login form will display a "Login with {displayName}" button.
Logo URL: If set, the Authing login form will display this icon on the button of "Login with {displayName}", which will be displayed as 20 * 20.
Issuer URL: The Issuer URL of the OpenID Connect provider you want to connect to
Client ID: Client ID of your OpenID Connect provider
Callback URL: You need to set the callback link of this OIDC IdP to https://core.authing.cn/connections/oidc/callback, please check the documentation of your OIDC IdP.

Click the Create button to complete the creation.

# Choose the connection mode that suits you

There are two modes for connecting to OIDC identity sources:

Front Channel: In this mode, the exchange of user information will all be done in the front end of the browser, and the response_mode=form_post and response_type=id_token modes will be used. Please make sure your OIDC application has turned on the implicit mode , And Return Type is checked with id_token

Back Channel: In this mode, the exchange of user information will be performed on the Authing server, and the authorization code mode of response_type=code will be used, so you need to provide the key of your OIDC application.

You can choose one of these modes according to your needs.

Select an application, click experience:

You can see that at the bottom of the form there is an additional button for Login with xxx, this is the OIDC connection you just configured:

Click this button, the browser will pop up a new window to the login page of the other party's OIDC IdP. Since we are using Authing's OIDC identity source here, we pop up another Authing login form:

After that, the browser window will be closed and return to the Authing login form. At the same time, you can see that the user is synchronized to the Authing user pool:

# Use the API interface to test this connection

If you want to use your own login page to complete the OIDC identity source connection, you can do it manually by calling the API:

# POST `start-interaction`

POST

https://core.authing.cn/api/v2/connections/oidc/start-interaction

When the user pool jumps back to the Authing server from the third-party OIDC IdP, Authing will determine the target user pool through the state in the callback parameter, so you need to call this interface to associate the state with the user pool.

Request

Body Paramter

state REQUIRED	string	Random string, which needs to be used as the state of subsequent OIDC requests
userPoolId REQUIRED	string	User pool ID
returnTo REQUIRED	string	Callback link

Response

200: OK

{
    code: 200,
    message: "ok"
}

This step is calling the interface of the third-party OIDC IdP. Different OIDC IdP invocation methods may be different. Here we take Authing's OIDC IdP as an example. **One thing to note is that the state when the login request is initiated must be consistent with the state in the first step. **

GET

https://yourAppDomain.authing.cn/oidc/auth

Splice a link and allow the end user to access it in the browser to initiate an OIDC authorization login request.

To initiate authorization, you need to splice a URL for authorization and allow end users to access it in a browser. The specific parameters are as follows:

Request

Query Parameters

client_id REQUIRED	string	Application ID.
redirect_uri REQUIRED	string	Callback link. After the user is successfully authenticated by the OP, the OP will send the authorization code to this address in the form of a URL query. This value must appear in the callback address of the console configuration, otherwise the OP is not allowed to call back to this address.
scope REQUIRED	string	The required permission must include openid. If you need to get your phone number and email, you need to include phone email; if you need refresh_token, you need to include offline_access. Please separate multiple scopes with spaces. id_token The decoded content will contain fields related to user information corresponding to these scopes.
response_type REQUIRED	string	The return type can be code, id_token, id_token token, code id_token, code token, code id_token token. After the login is successful, specify what information OP will return. If it contains code, OP will return the authorization code code, if it contains id_token, OP will return the user’s id_token, if it contains token, OP will return the user’s access_token.
prompt OPTIONAL	string	It can be none, login, consent or select_account. It specifies the interaction method between OP and End-User. If refresh_token is required, must be consent.
state REQUIRED	string	A random string used to prevent CSRF attacks. If the state value in the response is different from the state value set before sending the request, it means that it is under attack. The state here needs to be consistent with the state in the first step.
nonce OPTIONAL	string	A random string used to prevent Replay attacks.

# Receive user information

After the user agrees to the authorization in the previous step, it will first jump to the Authing server, and then Authing will carry the user information and jump to the returnTo parameter passed by the developer in the first step interface, with the following Get request parameters:

Parameters	Description
code	Error or success code, 200 is success, non-200 is failure
message	Success or error message
data	userInfo, if code is not 200, this parameter is not returned

Some browsers and Web Servers may have a 404 when the URL is too long, such as ASP.NET. At this time, you need to modify the configuration. For details, see [This StackOverflow Answer](https://stackoverflow.com/questions/ 28681366/in-asp-net-mvc-would-a-querystring-too-long-result-in-404-file-not-found-error/28681600).

The following is the code that uses JavaScript to get user data from URL parameters:

// Get URL parameters
function getQueryString(name) {
  var reg = new RegExp("(^|&)" + name + "=([^&]*)(&|$)", "i");
  var r = window.location.search.substr(1).match(reg);
  if (r != null) {
    return unescape(r[2]);
  }
  return null;
}

// Convert Code to Int type to facilitate judgment
const code = parseInt(getQueryString("code"));

if (code !== 200) {
  // error
  const errorMsg = getQueryString("message");
  // Show errorMsg to users or perform other business...
} else {
  const userInfo = getQueryString("data");

  // Store token in localStorage
  // It is recommended to attach the Token to the subsequent request, and verify the validity of the Token by the backend
  localStorage.setItem("token", userInfo.token);
}

# Next Step

After obtaining the user information, you can get the login credential token. You can carry this token in subsequent API requests, and then distinguish different users based on this token in the backend interface. For details, see [Verification token](../ ../advanced/verify-jwt-token.md#yan-zheng-authing-qian-fa-de-token).