Hide Comments

The securityScheme keyword defines and configures a security scheme, which may be applied to control access to the methods defined in an API.

Syntax

securityScheme <scheme-name>

type (basic | oauth2 | custom)

[methodInvocation

[requires authorization

<method-auth-param>...]

[errorResponse statusCode <error-status-code>]...]

[[~defines] scopes

<auth-scope>...]

[[~uses] flow <auth-flow>...]

[settings

(<setting-name> : "<setting-value>")...]        

Examples

/** HTTP Basic authentication.

   https://www.ietf.org/rfc/rfc2617.txt */

securityScheme Basic

type basic

methodInvocation

requires authorization

/** userid and password, separated by a single colon (":") character, within a

base64 [7] encoded string in the credentials.*/

param basic_credentials type base64Binary in header

errorResponse statusCode 401 //Unauthorized

/** OAuth2 authentication.

   https://tools.ietf.org/rfc/rfc6749.txt */

securityScheme OAuth2

type oauth2

methodInvocation

requires authorization

param token type string in header

param access_token type string in query

errorResponse statusCode 401

defines scopes

/** System administator. */

admin

/** Read-only user */

user

/** Manager of the system */

manager

settings

authorization_url : "http://test.com/oauth/authorize"

request_token_url : "http://test.com/oauth/oauth/request-token"

Parameters

Name

Type

Description

<scheme-name>

Name

Name assigned to this Security Scheme Definition.

basic

keyword

Indicates that this scheme uses Basic Authentication, as defined in IETF RFC 2617.

oauth2

keyword

Indicates that this scheme uses the OAuth 2.0 Authorization Framework defined in IETF RFC 6749.

custom

keyword

Indicates that this scheme uses a custom authentication/authorization framework.  RAPID-ML can accommodate custom security schemes, to the extent that they can be configured using the provided security scheme parameters.

<error-status-code>

integer

A status code which MAY be returned from the secured Method in the event of an authorization failure.

<auth-scope>

Name

Defines a named scope used within this security scheme.  For security schemes that define authorization scopes, the Security Scheme Application SHOULD specify the scope(s) that apply to the applicable Method.  In the OAuth example above, some methods may be available only to users authenticated at the manager or admin level.
 
OAuth 2.0 defines scopes as part of the protocol.  Custom security schemes MAY also use scopes.  While scopes MAY also be specified for a Basic security scheme, they have no meaning in that context.

<auth-flow>

SName

Specifies an OAuth 2.0 defined flow, which MUST be one of the following values:  ACCESS_CODE, APPLICATION, IMPLICIT, or PASSWORD.
 
This parameter is specific to OAuth 2.0.  However, it MAY be specified for any security scheme, and may be ascribed special meaning for custom security schemes.

<setting-name>

Name

The name assigned to a setting, used to configure the security scheme.  Any legal name is permissible, but the following OAuth 2.0 settings are pre-defined, and SHOULD be offered as available setting names by RAPID-ML editors:

access_token_url
authorization_url
redirect_url
request_token_url
token_url                                

<setting-value>

string

The value assigned to a setting.

Child Elements

Name

Topic

Description

<method-auth-param>

Message Parameter

Specifies a Message Parameter that must be passed in the secured Method request, to authenticate the client or to authorize access to the Method.
 
As with standard message parameters, the Method authorization parameter may specify a data type and location (in the header or query string).  However, Method authorization parameters may not be bound to a property of a Data Structure.

Parent Elements

Security Schemes Library

Created with Help & Manual 6 and styled with Premium Pack Version 2.51 © by EC Software