External Authentication Providers

OpenDrives systems allow users to authenticate against a third party authentication provider. These ‘external providers’ are not inherent to an OpenDrives system, but are accessed externally via https. This is commonly known as Single Sign On (SSO) and we allow custom entries to any third party provider which conform to either OAuth 2.0 or SAML protocol.

Examples of using external provider authentication is logging in to an OpenDrives system using Okta, Google, or Facebook.

Basic Operations

Basic operations of Create, Update, Read, Delete, List are available.

Note: the List route returns a list of ALL providers, both internal and external. The provider type which is noted in the provider_type field where string int implies internal provider and string ext implies external provider.

List Providers

Get a list of all providers set up on an OpenDrives system

+ URL
  /api/v2/authorization/provider

+ Method
  GET

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

Returns an array of providers

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [
    {
        "provider_type": "int",
        "provider_name": "saitamaonepunch",
        "provider_protocol": "ldap",
        "raw": "[domain/one.punch]\n\tid_provider = ldap\n\tldap_uri = ldap://saitama.one.punch\n\tldap_search_base = dc=one,dc=punch\n\tldap_id_use_start_tls = true\n\tldap_tls_reqcert = demand\n\tldap_tls_cacert = /etc/ssl/certs/bind_ldap.crt\n\tauth_provider = krb5\n\tkrb5_server = saitama.one.punch\n\tkrb5_realm = ONE.PUNCH\n\tcache_credentials = True\n\tdebug_level = 9\n",
        "json": {
            "domain/one.punch": {
                "id_provider": "ldap",
                "ldap_uri": "ldap://saitama.one.punch",
                "ldap_search_base": "dc=one,dc=punch",
                "ldap_id_use_start_tls": "true",
                "ldap_tls_reqcert": "demand",
                "ldap_tls_cacert": "/etc/ssl/certs/bind_ldap.crt",
                "auth_provider": "krb5",
                "krb5_server": "saitama.one.punch",
                "krb5_realm": "ONE.PUNCH",
                "cache_credentials": "True",
                "debug_level": "9"
            }
        }
    },
    {
        "provider_name": "imgur",
        "provider_protocol": "oauth",
        "provider_type": "ext",
        "options": {
            "callbackURL": "https://192.168.7.62:1337/api/v2/authorization/login/callback",
            "clientID": "myClientId",
            "clientSecret": "myClientSecret",
            "authorizationURL": "https://api.imgur.com/oauth2/authorize",
            "tokenURL": "https://api.imgur.com/oauth2/token",
            "userProfileURL": "https://api.imgur.com/3/account/me"
        },
        "enabled": true,
        "host": "192.168.7.62:8080",
        "hostid": "ae82a9a2"
    }
  ]

Get External Provider

Get details on an individual external provider

Request Object

+ URL
  /api/v2/authorization/provider/external/$PROVIDER_NAME/details

+ Method
  GET

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

Returns an object with external provider settings

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
    {
      "provider_name": "imgur",
      "provider_protocol": "oauth",
      "provider_type": "ext",
      "options": {
          "callbackURL": "https://192.168.7.62:1337/api/v2/authorization/login/callback",
          "clientID": "myClientId",
          "clientSecret": "myClientSecret",
          "authorizationURL": "https://api.imgur.com/oauth2/authorize",
          "tokenURL": "https://api.imgur.com/oauth2/token",
          "userProfileURL": "https://api.imgur.com/3/account/me"
      },
      "enabled": true,
      "host": "192.168.7.62:8080",
      "hostid": "ae82a9a2"
  }

Create External Provider

Create an external provider on your OpenDrives system

Request Object

+ URL
  /api/v2/authorization/provider/add

+ Method
  POST

+ Parameters
  provider_name: (string, required) - custom name of provider
  provider_protocol: (string, required) - procotol used for provider (i.e saml or oauth)
  host: (string, required) - host of OpenDrives system (i.e 192.168.7.62, hostname.opendrives.com)
  options: (object, required) - parameters to connect to external provider service. See passport.js docs for more information on specific SAML and Oauth 2.0 parameters.

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "provider_name": "imgur",
    "provider_protocol": "oauth",
    "options": {
        "callbackURL": "https://192.168.7.62:1337/api/v2/authorization/login/callback",
        "clientID": "myClientId",
        "clientSecret": "myClientSecret",
        "authorizationURL": "https://api.imgur.com/oauth2/authorize",
        "tokenURL": "https://api.imgur.com/oauth2/token",
        "userProfileURL": "https://api.imgur.com/3/account/me",
    }
    "host": "192.168.7.62:8080"
    },
  }

Response Object

Returns external provider database entry

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [
    {
        "id": 4,
        "hostid": "ae82a9a2",
        "host": "192.168.7.62:8080",
        "provider_name": "imgur",
        "provider_protocol": "oauth",
        "enabled": true,
        "options": {
            "authorizationURL": "https://api.imgur.com/oauth2/authorize",
            "tokenURL": "https://api.imgur.com/oauth2/token",
            "clientID": "myClientId",
            "clientSecret": "myClientSecret",
            "callbackURL": "https://192.168.7.62:1337/api/v2/authorization/login/callback",
            "userProfileURL": "https://api.imgur.com/3/account/me/"
        },
        "createdAt": "2020-12-07T19:46:55.045Z",
        "updatedAt": "2020-12-07T19:46:55.045Z"
    }
  ]

Remove External Provider

Removes an external provider from your OpenDrives system

Request Object

+ URL
  /api/v2/authorization/provider/$PROVIDER_NAME/remove

+ Method
  GET

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

Returns the external provider database entry that was removed from the OpenDrives system

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [
    {
        "id": 4,
        "hostid": "ae82a9a2",
        "host": "192.168.7.62:8080",
        "provider_name": "imgur",
        "provider_protocol": "oauth",
        "enabled": true,
        "options": {
            "authorizationURL": "https://api.imgur.com/oauth2/authorize",
            "tokenURL": "https://api.imgur.com/oauth2/token",
            "clientID": "myClientId",
            "clientSecret": "myClientSecret",
            "callbackURL": "https://192.168.7.62:1337/api/v2/authorization/login/callback",
            "userProfileURL": "https://api.imgur.com/3/account/me/"
        },
        "createdAt": "2020-12-07T19:46:55.045Z",
        "updatedAt": "2020-12-07T19:46:55.045Z"
    }
  ]

Update External Provider

Updates an existing external provider on your OpenDrives system.

Note: this will overwrite any existing entry for the external provider and all parameters must exist in order to update. If you are not updating a specific parameter you should still provide that parameters information. See example below in request body and response body. For example, if you want to update just the provider_name you should pass in the updated provider_name along with the existing provider_protocol, host, and options

Request Object

+ URL
  /api/v2/authorization/provider/$PROVIDER_NAME/update

+ Method
  POST

+ Parameters
  provider_name: (string, required) - custom name of provider
  provider_protocol: (string, required) - procotol used for provider (i.e saml or oauth)
  host: (string, required) - host of OpenDrives system (i.e 192.168.7.62, hostname.opendrives.com)
  options: (object, required) - parameters to connect to external provider service. See passport.js docs for more information on specific SAML and Oauth 2.0 parameters.

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "provider_name": "imgur",
    "provider_protocol": "oauth",
    "options": {
        "callbackURL": "https://192.168.7.62:1337/api/v2/authorization/login/callback",
        "clientID": "myNewClientId",
        "clientSecret": "myNewClientSecret",
        "authorizationURL": "https://api.imgur.com/oauth2/authorize",
        "tokenURL": "https://api.imgur.com/oauth2/token",
        "userProfileURL": "https://api.imgur.com/3/account/me"
    },
  }

Response Object

Returns the external provider database entry that was removed from the OpenDrives system

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [
    {
        "id": 5,
        "provider_name": "imgur",
        "provider_protocol": "oauth",
        "hostid": "ae82a9a2",
        "host": "192.168.7.62:8080",
        "enabled": true,
        "options": {
            "authorizationURL": "https://api.imgur.com/oauth2/authorize",
            "tokenURL": "https://api.imgur.com/oauth2/token",
            "clientID": "myNewClientId",
            "clientSecret": "myNewClientSecret",
            "callbackURL": "https://192.168.7.62:1337/api/v2/authorization/login/callback",
            "userProfileURL": "https://api.imgur.com/3/account/me/"
        },
        "createdAt": "2020-12-07T19:46:55.045Z",
        "updatedAt": "2020-12-07T19:46:55.045Z"
    }
  ]