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",
"domain": "one.punch",
"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"
}
]