Single Sign-On (SSO)

Single Sign-On (SSO) allows users to authenticate with K12NET through your application, providing a seamless and secure user experience. Here's how you can implement SSO as a Partner:

To integrate Single Sign-On (SSO) into your application, enabling users to log in with their K12NET credentials, follow these straightforward steps:

  1. Create a Login Link: Incorporate a link or button within your application labeled "Login with K12NET". This serves as the entry point for users to authenticate via K12NET.

  2. Redirect Users for Authentication: When users click the "Login with K12NET" link, redirect them to the K12NET authentication page. Ensure to include your application's client_id and the redirect_uri in the request. The redirect_uri is the URL where users should be directed after a successful login.

  3. Capture the Authorization Code: After the user successfully logs in, K12NET will redirect them back to the redirect_uri you specified, appending an authorization_code to the query string. Capture this authorization_code from the user's browser's query string for the next step.

  4. Verify the User: With the authorization_code in hand, make a request to the K12NET token endpoint to exchange it for an access_token. Then, query the /userinfo endpoint using this access_token to retrieve the user's information and verify their identity.

By following these steps, you can securely authenticate users with their K12NET credentials, streamlining the login process for your application while maintaining high security standards. This SSO integration ensures a seamless user experience for accessing both K12NET's functionalities and your application's services.

Direct User for Authentication

To initiate the SSO process, direct the user to our authorization endpoint with the necessary query parameters. Here's the URL format you should use: profile

Replace YOUR_CLIENT_ID with your client identifier and YOUR_REDIRECT_URI with the URI where you want the user to be redirected after authentication.

Handle the Authorization Code

After the user has logged in, a code will be returned to your application via the redirect URI. This code is used to request an access_token.

Request Access Token

Make a POST request to our token endpoint to exchange the code for an access_token.

curl -X POST \
-d "grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded"

Replace placeholders with actual values including the YOUR_AUTHORIZATION_CODE you received after the user's successful login.

Retrieve User Information

Once you have the access_token, you can request the user's information by making a GET request to the userinfo endpoint:

curl -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Replace YOUR_ACCESS_TOKEN with the actual access token you obtained.

This will return the user's information, which you can then use within your application according to the permissions granted.

Upon successfully obtaining the access_token and making a GET request to the userinfo endpoint, you will receive a JSON response containing the user's information. Here is the format of the response:

  "ID": "{b1e15c95-011b-ee11-8137-bc97e1afd933}",
  "profile": "Student",
  "sub": "54847847844"

The ID field contains the unique identifier of the user within K12NET. This identifier is essential for associating the user's data with your application's internal records.

This unique identifier is essential for making subsequent API calls related to the user. It is used to reference the specific user in your application and should be securely stored and handled. Any API requests that require user-specific information will need this ID to retrieve or modify data pertaining to that user in the K12NET system.

The profile field indicates the role of the user within K12NET and can be one of the following values:

This information is critical for determining the user's access level and permissions within your application. Ensure that your application logic handles each user type appropriately to provide a tailored experience.

Remember to handle these requests securely and maintain the confidentiality of all credentials and tokens. The actual implementation may vary depending on the specific setup of your application and should align with best security practices.

To further facilitate the integration of Single Sign-On (SSO) capabilities, we provide a range of additional endpoints that allow Partners to retrieve specific user information. These endpoints are designed to give Partners access to detailed data for students and teachers once SSO authentication is completed. Below are the endpoints and their functionalities:

Acquire Authorization Token: You need to obtain an authorization token to access the K12NET API. This token is used to authenticate your requests and ensure that you have the necessary permissions to access the data. To acquire the authorization token, you need to make a POST request to the token endpoint with your client credentials. Here's an example of how to do this:

curl -X POST 
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" 
-H "Content-Type: application/x-www-form-urlencoded"

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual client credentials. The response to this request will include an access_token that you can use to authenticate your subsequent requests. You need to include this token in the Authorization header of your API requests.

Retrieve Student Information: Once you have obtained an authorization token, you can use it to retrieve detailed information about students. The following endpoints are available for accessing student data:

It is important to note that the JSON fields returned from these endpoints are controlled by the respective Organization. This means that certain information, such as BirthDate in the demographics endpoint, may be available for users in one Organization but not in another. This customizable aspect ensures that each Organization retains control over what data is shared and adheres to their privacy and data governance policies. Partners must handle the data conditionally and ensure that their applications are designed to gracefully handle the presence or absence of specific fields.