Authentication and Web Security

The Cisco NAE REST API server protects API sessions against common web threats as described in the following sections.

User Accounts and Roles

Most functions of the Cisco NAE REST API require that the user be authenticated and logged in with an active session. The REST API supports both local authentication and LDAP authentication.

Two roles are supported for user accounts:

User: Normal user accounts can be created locally or on a remote authentication server. Some APIs cannot be executed by a normal user.
Super Administrator: The local account named admin is considered a super administrator, with higher privileges than a normal user. When logged in as admin, you can execute several APIs that are not allowed for normal users. The admin account is permanent and cannot be deleted.

Logging in to the Cisco NAE

To prevent a Cross Site Request Forgery (CSRF) attack and other common web threats, the REST API server implements a multi-step login sequence in order to issue a unique session token.

NOTE: For more information about CSRF, visit https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_

The following steps describe the login sequence:

The client sends an HTTP GET request to /nae/api/v1/whoami.
The server returns an HTTP response that includes an X-NAE-LOGIN_OTP header containing a one-time password (OTP) with a five-minute expiration.
The client sends an HTTP POST request to /nae/api/v1/login with local or LDAP authentication credentials and with an HTTP request header field of X-NAE-LOGIN_OTP containing the OTP value.
If the credentials are valid, the server returns an HTTP response that includes an X-NAE-CSRF-TOKEN header containing a session password.
For all subsequent POST/PUT/DELETE messages for the duration of the session, the client must include the X-NAE-CSRF-TOKEN header in the HTTP request.

The following table summarizes the use of the request and response headers:

Request URI	Request Header Name	Response Header Name	Notes
/nae/api/v1/whoami	None	X-NAE-LOGIN-OTP	The OTP is returned in the header only if the user is not already authenticated.
/nae/api/v1/loginv	X-NAE-LOGIN-OTP	X-NAE-CSRF-TOKEN	The OTP header is sent with the login request. The response header must be included in all subsequent API requests for the duration of the session.
/nae/api/v1/*	X-NAE-CSRF-TOKEN	N/A	The request header is required for all API(GET/POST/PUT/DELETE) operations.

The following example session shows the login sequence:

Whoami request sent by unauthenticated client

Request

Code Snippet

CopyGET /nae/api/v1/whoami HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

Response

json

CopyHTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-NAE-LOGIN-OTP: 6c2edd3b-c334-4a25-a1a4-b1b8f554c856
Set-Cookie: SESSION=84eb7ce2-325c-44d1-9f2e-5531dfcb6361; Path=/; HttpOnly
Content-Length: 684

{
  "success" : true,
  "messages" : [ {
    "code" : 7005,
    "severity" : "INFO",
    "message" : "User is not authenticated.  Use One Time Password found in the response header X-NAE-LOGIN-OTP within the next 5 minutes to login"
  } ],
  "value" : {
    "namespaces" : {
      "default" : "https://www.cisco.com/api/schema"
    },
    "data" : {
      "authenticated" : false
    },
    "data_summary" : {
      "links" : [ {
        "rel" : "self",
        "href" : "http://localhost:8080/nae/api/v1/whoami"
      }, {
        "rel" : "login",
        "href" : "https://localhost:8080/nae/api/v1/login"
      } ],
      "total_count" : 1,
      "has_more_data" : false
    }
  }
}

Response headers

Name	Description
`X-NAE-LOGIN-OTP`	A one-time password to be sent in the HTML header of the /whoami API. The password expires five minutes after it is issued.

Request headers

Name	Description
`X-NAE-LOGIN-OTP`	One-time password that was sent in the HTML header of the /whoami API must be provided here.

Request

json

CopyPOST /nae/api/v1/login HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept: application/json
X-NAE-LOGIN-OTP: f846abb8-2505-4b81-8776-13e7c4ae4d2f
Host: localhost:8080
Content-Length: 122
Cookie: SESSION=de3c0f55-6780-4c5a-a6c5-bf3589e9fe4c

{
  "username" : "NbUserRepositoryTestiBPtABUOsQ",
  "password" : "NbUserRepositoryTestiBPtABUOsQ",
  "domain" : "Local"
}

Response

json

CopyHTTP/1.1 200 OK
X-NAE-CSRF-TOKEN: 7f02df02-e9ee-4717-9ea1-6917cf4f3060
Content-Type: application/json;charset=UTF-8
Set-Cookie: SESSION=d533e319-c8b8-47c5-a313-88f67cda9b9f; Path=/; HttpOnly
Content-Length: 535

{
  "success" : true,
  "value" : {
    "namespaces" : {
      "default" : "https://www.cisco.com/api/schema"
    },
    "data" : {
      "username" : "NbUserRepositoryTestiBPtABUOsQ",
      "uuid" : "c331aa76-aa0e-43a4-a7b8-b2f8d4a5e6f4",
      "domain" : "Local",
      "password_status" : "ACTIVE",
      "remaining_days" : 0
    },
    "data_summary" : {
      "links" : [ {
        "rel" : "self",
        "href" : "https://localhost:8080/nae/api/v1/login"
      } ],
      "total_count" : 1,
      "has_more_data" : false
    }
  }
}

Response headers

Name	Description
`X-NAE-CSRF-TOKEN`	A random token that is valid for the entire session and must be submitted in the X-NAE-CSRF-TOKEN request header of every GET/POST/PUT/DELETE request.

Logout request sent by authenticated client

Request headers

Name	Description
`X-NAE-CSRF-TOKEN`	The token that is generated as part of login request must be submitted here.

Request

Code Snippet

CopyPOST /nae/api/v1/logout HTTP/1.1
Content-Type: application/json
Accept: application/json
X-NAE-CSRF-TOKEN: 8bf4c138-0977-431d-872b-d7fd944e04e6
Cookie: SESSION=568af5d5-5e74-4c7d-be25-5ad04b5a26aa

Response

json

CopyHTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 318

{
  "success" : true,
  "value" : {
    "namespaces" : {
      "default" : "https://www.cisco.com/api/schema"
    },
    "data_summary" : {
      "links" : [ {
        "rel" : "whoami",
        "href" : "http://localhost:8080/nae/api/v1/whoami"
      } ],
      "total_count" : 0,
      "has_more_data" : false
    }
  }
}

Whoami request sent by authenticated client (optional)

Request

Code Snippet

CopyGET /nae/api/v1/whoami HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080
Cookie: SESSION=6b603f2b-e8d7-45cf-9483-15ad6cebd8e8

Response

json

CopyHTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 675

{
  "success" : true,
  "messages" : [ {
    "code" : 7003,
    "severity" : "INFO",
    "message" : "The user is already authenticated to this session"
  } ],
  "value" : {
    "namespaces" : {
      "default" : "https://www.cisco.com/api/schema"
    },
    "data" : {
      "authenticated" : true,
      "password_status" : "ACTIVE",
      "domain" : "Local",
      "uuid" : "9202dae4-a6a4-4957-8840-594936923b9d",
      "username" : "NbUserRepositoryTestEhUWTrYgGN"
    },
    "data_summary" : {
      "links" : [ {
        "rel" : "self",
        "href" : "http://localhost:8080/nae/api/v1/whoami"
      } ],
      "total_count" : 1,
      "has_more_data" : false
    }
  }
}

Response headers

Path	Type	Description
`messages`	`Array`	Descriptive messages provided for this request
`messages[].code`	`Number`	An error code indicating that the user is already authenticated
`messages[].severity`	`String`	The severity level of this message, which is informational
`messages[].message`	`String`	An informational message indicating that the user is already authenticated
`value.data.domain`	`String`	User authentication domain name
`value.data.authenticated`	`Boolean`	If true, the user is already authenticated
`value.data.username`	`String`	The user name of the user who is currently logged in
`value.data.password_status`	`String`	Password status. Possible values: ACTIVE, EXPIRED, EXPIRY_WARNING, LOCKED
`value.data.uuid`	`String`	The UUID of the user who is currently logged in
`value.data_summary.links`	`Array`	An array of links relevant to this request
`value.data_summary.links[].rel`	`String`	A keyword indicating the type of link in the "href" field. In this case, the provided link is a self link.
`value.data_summary.links[].href`	`String`	A link to the resource identified by the "rel" keyword. In this case, the URL is a self link for this request.

Additional Web Security Measures

Concurrent Session Protection

The Cisco NAE REST API server limits the number of concurrent active sessions for a single user account.

Session Fixation Protection

The Cisco NAE REST API server provides a mechanism for preventing session fixation attacks.

NOTE: For more information about Session Fixation protection, visit https://www.owasp.org/index.php/Session_Fixation_Protection

XSS Protection

The Cisco NAE REST API server provides XSS (Cross Site Scripting) prevention.

NOTE: For more information about XSS protection, visit https://www.owasp.org/index.php/XSS

Authentication and Web Security

User Accounts and Roles

Logging in to the Cisco NAE

API login example

Whoami request sent by unauthenticated client

Request

Response

Response headers

Login request sent by unauthenticated client

Request headers

Request

Response

Response headers

Logout request sent by authenticated client

Request headers

Request

Response

Whoami request sent by authenticated client (optional)

Request

Response

Response headers

Additional Web Security Measures

Concurrent Session Protection

Session Fixation Protection

XSS Protection