Single sign-on (SSO) is an authentication method that allows users to securely authenticate to multiple applications and services using only one set of credentials. By implementing SSO integration with Ringotel, you enable users to authenticate with their Ringotel app using the same credentials they use to authenticate to your own app or service.

To enable the SSO integration for your account, please send request to support@ringotel.co

Prerequisites

To implement SSO integration with Ringotel (Service Provider), you need the following:

Deploy a web service (Identity Provider) able to receive and respond to HTTPS requests with JSON content.
Your web service needs to be able to authorize requests from a Ringotel server using Basic, Bearer, or OAuth2 method.
Your web service should be able to accept users' credentials, match them with the username/passwrod in your service and reply with the standard 200 OK or 403 Forbidden HTTP codes.
In case of a successful user authentication, your web server must return standard HTTP 200 OK code and the list of usernames associated with a Ringotel user.

Implementation

You must implement an HTTPS endpoint on your web service where Ringotel will send requests as a part of the login flow.

User authentication flow

Ringotel → https://<your web server>/authorize

POST /auth
Authorization: Basic/Bearer/OAuth2
Content-Type: application/json

{
	"username": "string",
	"password": "string"
}

https://<your web server> → Ringotel

Your web server must reply with 200 OK (username/password is correct, the user is Authenticated) or 403 Forbidden (username/password is wrong, the user is Unauthenticated) and provide the list of usernames associated with a Ringotel user in the request body.

Example

An example below provides the integration description in the JSON format that is used in Ringotel. This examples uses OAuth2 authorization mechanism to authorize requests from the Ringotel server to the provider’s web server. However, Basic or Bearer authorization can be used instead.

{
    "id":	"yourserviceid",
    "name":	"Your service name",
    "logo": "https://assets.example.com/img/services/logo.png",

    "class":"auth",

    "parameters": {
        "user_id":          "string",
        "username":         "string",
    },
    
    "properties":[
    ],

    "resource_url": "https://api.example.com/users",
    
    "OAuth2": {
        "client_id": "<client_id>",
        "client_secret": "<client_secret>",
        "flow_type": {
            "default": "3"
        },
        "token_endpoint": "https://api.example.com/oauth/token",
        "token_parameters": {
            "content_type": "application/json",
            "request_headers": {
                "Custom-Header": "<custom_header_value>"
            }
        },
        "request_auth": "Bearer",
    },
    
    "API": {
        
        "authenticate": {
            "request_method": "POST",
            "request_url": "https://api.example.com/users",
            "request_content_type": "application/json",
            "request_headers": {
                "Custom-Header": "<custom_header_value>"
            },
            "request_parameters":
            {
                "email": "$username$",
                "password": "$password$",
            },
            "response_map":
            {
                "values": [
                    {
                        "username": "$username$",
                        "display_name": "$displayname$"
                    }
                ]
            }

        }
    }
}

Ringotel Shell Wiki

Single Sign-On (SSO) Integration

Prerequisites

Implementation

Example