Custom securitySchemes in 0.8 RAML to HTML


#1

I’ve become interested in following RAML, but got stuck with a specific scenario in which I’d like to describe a JSON Web Token security design for services and use RAML2HTML. I’ve referenced the 0.8 Security section under the specification, but I haven’t had success using the other securityScheme type yet. Below is where I’ve taken the notes example partially and simply added a securitySchemes section. I’ve tried different variations starting with customHeader as described in the specification, but could only get the parser to work by removing the securitySchemes section and securedBy for the user get. Would anybody else have successfully described another security design using something other than OAuth 1.0 or OAuth 2.0? I’m not sure if this could be a valid raml-js-parser issue or how I’m creating the RAML just yet.

#%RAML 0.8
title: Notes Example API
version: v2
mediaType: application/json
baseUri: http://localhost:8080/api
documentation:

  • title: Overview
    content: This is an example of a simple API for a “notes” service
    securitySchemes:
    • x-{.custom}:
      description: A custom
      /user:
      get:
      securedBy: [custom]
      description: Retrieve all the active users

#2

Hi Justin,

thanks for using RAML :slight_smile:

The following is an example of using custom security schemas:

securitySchemes:
  - myCustomSec:
      describedBy:
        queryParameters:
          token:
            description: provide token
            type: string
            example: ABS-SDF
      type: x-myCustomSec

Hope that makes sense and it helps you?

Cheers,
Christian


#3

Thank you very much, Christian! Your sample plugged right in so I could produce the desired html and made it clear what I was doing wrong so I could move forward. I’ll include the complete raml and sample output.

#%RAML 0.8
title: Notes Example API
version: v2
mediaType: application/json
baseUri: http://localhost:8080/api
documentation:
  - title: Overview
      content: This is an example of a simple API for a "notes" service
securitySchemes:
  - myCustomSec:
      describedBy:
        queryParameters:
           token:
             description: provide token
             type: string
             example: ABS-SDF
      type: x-myCustomSec
/user:
  get:
    securedBy: [myCustomSec]
    description: Retrieve all the active users


#4

Awesome :wink:


#5

I have a similar use case.

But above the authentication scheme, I would like to specify who is authorised to use certain resources.
Access is granted based on the role claim that is contained in the token

How can I describe this in RAML?

Thanks!


#6

I would love to understand how best to describe “roles”, ACL, etc within RAML as well. It would be fantastic for example to include response chunks based on roles/acl, such that for a given resource that could be accessed say by a normal user and an admin user, the admin user might see more data in the response. Also, it would be ideal if there was a way to generate output based on roles/acl… such that I could generate output for 1 role, such as admins. That way I could generate artifacts for different groups of consumers. For example, internal company developers, or public API consumers could see different resources and such.