From f7ac6622b42276c4ab9945e780b061142a8b48e1 Mon Sep 17 00:00:00 2001 From: jricher Date: Fri, 26 Apr 2013 11:23:48 -0700 Subject: [PATCH] Updated Api (markdown) --- Api.md | 345 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 332 insertions(+), 13 deletions(-) diff --git a/Api.md b/Api.md index c4d1131..6c97edd 100644 --- a/Api.md +++ b/Api.md @@ -1,25 +1,344 @@ -# Clients +The MITREid Connect server has a robust RESTful API that is used to manage various aspects of the server's configuration. In fact, the administration UI is really just a JavaScript application that uses this RESTful API to do its job. -`/api/clients` +## Clients -## GET /api/clients +Endpoint: `/api/clients` -*Note:* This method will return different information depending on whether or not the authorized user is an administrator. +Manages all registered clients on the system, both statically and dynamically registered. -## POST /api/clients +### GET /api/clients -## GET /api/clients/{id} +Get a list of all clients on the system, returns results in `application/json`. -*Note:* This method will return different information depending on whether or not the authorized user is an administrator. +``` +[ -## PUT /api/clients/{id} + { + "id": 1, + "clientId": "client", + "clientSecret": "secret", + "redirectUris": [ + "http://localhost/", + "http://localhost:8080/" + ], + "clientName": "Test Client", + "clientUri": null, + "logoUri": null, + "contacts": [ ], + "tosUri": null, + "tokenEndpointAuthMethod": null, + "scope": [ + "phone", + "openid", + "offline_access", + "address", + "email", + "profile" + ], + "grantTypes": [ + "implicit", + "authorization_code", + "urn:ietf:params:oauth:grant_type:redelegate", + "refresh_token" + ], + "responseTypes": [ ], + "policyUri": null, + "jwksUri": null, + "applicationType": null, + "sectorIdentifierUri": null, + "subjectType": null, + "requestObjectSigningAlg": null, + "userInfoSignedResponseAlg": null, + "userInfoEncryptedResponseAlg": null, + "userInfoEncryptedResponseEnc": null, + "idTokenSignedResponseAlg": null, + "idTokenEncryptedResponseAlg": null, + "idTokenEncryptedResponseEnc": null, + "defaultMaxAge": null, + "requireAuthTime": null, + "defaultACRvalues": [ ], + "initiateLoginUri": null, + "postLogoutRedirectUri": null, + "requestUris": [ ], + "authorities": [ ], + "accessTokenValiditySeconds": 3600, + "refreshTokenValiditySeconds": null, + "resourceIds": [ ], + "clientDescription": null, + "reuseRefreshToken": true, + "dynamicallyRegistered": false, + "allowIntrospection": true, + "idTokenValiditySeconds": 600, + "createdAt": null + } -## DELETE /api/clients/{id} +] +``` +*Note:* This method will return different information depending on whether or not the authorized user is an administrator. A non-administrator will get a limited set of information back: -# Whitelists +``` +[ -# Blacklists + { + "id": 1, + "clientId": "client", + "clientName": "Test Client", + "logoUri": null, + "scope": [ + "phone", + "openid", + "offline_access", + "address", + "email", + "profile" + ], + "clientDescription": null + } +] +``` -# System Scopes +### POST /api/clients -# User Site Approvals \ No newline at end of file +Create a new client on the system. Message body is an `application/json` object with all client parameters: + +``` +{ + "id": 1, + "clientId": "client", + "clientSecret": "secret", + "redirectUris": [ + "http://localhost/", + "http://localhost:8080/" + ], + "clientName": "Test Client", + "clientUri": null, + "logoUri": null, + "contacts": [ ], + "tosUri": null, + "tokenEndpointAuthMethod": null, + "scope": [ + "phone", + "openid", + "offline_access", + "address", + "email", + "profile" + ], + "grantTypes": [ + "implicit", + "authorization_code", + "urn:ietf:params:oauth:grant_type:redelegate", + "refresh_token" + ], + "responseTypes": [ ], + "policyUri": null, + "jwksUri": null, + "applicationType": null, + "sectorIdentifierUri": null, + "subjectType": null, + "requestObjectSigningAlg": null, + "userInfoSignedResponseAlg": null, + "userInfoEncryptedResponseAlg": null, + "userInfoEncryptedResponseEnc": null, + "idTokenSignedResponseAlg": null, + "idTokenEncryptedResponseAlg": null, + "idTokenEncryptedResponseEnc": null, + "defaultMaxAge": null, + "requireAuthTime": null, + "defaultACRvalues": [ ], + "initiateLoginUri": null, + "postLogoutRedirectUri": null, + "requestUris": [ ], + "authorities": [ ], + "accessTokenValiditySeconds": 3600, + "refreshTokenValiditySeconds": null, + "resourceIds": [ ], + "clientDescription": null, + "reuseRefreshToken": true, + "dynamicallyRegistered": false, + "allowIntrospection": true, + "idTokenValiditySeconds": 600, + "createdAt": null +} +``` + +Any omitted values will be filled in with appropriate defaults in the following manner: + +- If `clientId` is empty, a new client id will be generated by the server +- If `clientSecret` is empty and a field named `generateSecret` is sent and set to `true`, then a new client secret will be generated by the server +- If `scope` is omitted or null, all system scopes marked as "default" will be assigned to the client + +The server will return an updated copy of the object in `application/json` format as described under **GET /api/clients/{id}**. + +### GET /api/clients/{id} + +Get information about a specific client identified by {id} in the url, in `application/json` format. + +For example, the call to `/api/clients/1` would return: + +``` +{ + "id": 1, + "clientId": "client", + "clientSecret": "secret", + "redirectUris": [ + "http://localhost/", + "http://localhost:8080/" + ], + "clientName": "Test Client", + "clientUri": null, + "logoUri": null, + "contacts": [ ], + "tosUri": null, + "tokenEndpointAuthMethod": null, + "scope": [ + "phone", + "openid", + "offline_access", + "address", + "email", + "profile" + ], + "grantTypes": [ + "implicit", + "authorization_code", + "urn:ietf:params:oauth:grant_type:redelegate", + "refresh_token" + ], + "responseTypes": [ ], + "policyUri": null, + "jwksUri": null, + "applicationType": null, + "sectorIdentifierUri": null, + "subjectType": null, + "requestObjectSigningAlg": null, + "userInfoSignedResponseAlg": null, + "userInfoEncryptedResponseAlg": null, + "userInfoEncryptedResponseEnc": null, + "idTokenSignedResponseAlg": null, + "idTokenEncryptedResponseAlg": null, + "idTokenEncryptedResponseEnc": null, + "defaultMaxAge": null, + "requireAuthTime": null, + "defaultACRvalues": [ ], + "initiateLoginUri": null, + "postLogoutRedirectUri": null, + "requestUris": [ ], + "authorities": [ ], + "accessTokenValiditySeconds": 3600, + "refreshTokenValiditySeconds": null, + "resourceIds": [ ], + "clientDescription": null, + "reuseRefreshToken": true, + "dynamicallyRegistered": false, + "allowIntrospection": true, + "idTokenValiditySeconds": 600, + "createdAt": null +} +``` +*Note:* This method will return different information depending on whether or not the authorized user is an administrator. A non-administrator will get a limited set of information back: + +``` +{ + "id": 1, + "clientId": "client", + "clientName": "Test Client", + "logoUri": null, + "scope": [ + "phone", + "openid", + "offline_access", + "address", + "email", + "profile" + ], + "clientDescription": null +} +``` + +### PUT /api/clients/{id} + +Update the information for the client identified by {id} in the URL. The request body must be `application/json` describing the entire client object: + +``` +{ + "id": 1, + "clientId": "client", + "clientSecret": "secret", + "redirectUris": [ + "http://localhost/", + "http://localhost:8080/" + ], + "clientName": "Test Client", + "clientUri": null, + "logoUri": null, + "contacts": [ ], + "tosUri": null, + "tokenEndpointAuthMethod": null, + "scope": [ + "phone", + "openid", + "offline_access", + "address", + "email", + "profile" + ], + "grantTypes": [ + "implicit", + "authorization_code", + "urn:ietf:params:oauth:grant_type:redelegate", + "refresh_token" + ], + "responseTypes": [ ], + "policyUri": null, + "jwksUri": null, + "applicationType": null, + "sectorIdentifierUri": null, + "subjectType": null, + "requestObjectSigningAlg": null, + "userInfoSignedResponseAlg": null, + "userInfoEncryptedResponseAlg": null, + "userInfoEncryptedResponseEnc": null, + "idTokenSignedResponseAlg": null, + "idTokenEncryptedResponseAlg": null, + "idTokenEncryptedResponseEnc": null, + "defaultMaxAge": null, + "requireAuthTime": null, + "defaultACRvalues": [ ], + "initiateLoginUri": null, + "postLogoutRedirectUri": null, + "requestUris": [ ], + "authorities": [ ], + "accessTokenValiditySeconds": 3600, + "refreshTokenValiditySeconds": null, + "resourceIds": [ ], + "clientDescription": null, + "reuseRefreshToken": true, + "dynamicallyRegistered": false, + "allowIntrospection": true, + "idTokenValiditySeconds": 600, + "createdAt": null +} +``` + +Any omitted values will be filled in with appropriate defaults in the following manner: + +- If `clientId` is empty, a new client id will be generated by the server +- If `clientSecret` is empty and a field named `generateSecret` is sent and set to `true`, then a new client secret will be generated by the server +- If `scope` is omitted or null, all system scopes marked as "default" will be assigned to the client + +The server will return an updated copy of the object in `application/json` format as described under **GET /api/clients/{id}** on success. + +### DELETE /api/clients/{id} + +Deletes the client with the {id} in the URL. + +Returns HTTP 200 with an empty page on success. + +## Whitelists + +## Blacklists + +## System Scopes + +## User Site Approvals \ No newline at end of file