iam - monetplus/IDport GitHub Wiki

Product IAM APIs v1.1.1

Overview

This is a specification of APIs which serve needs of Identity Access Management [external] & authentication server CASE.

Swagger YAML

Version information

Version : 1.1.1

License information

License : © Monet+, a.s.
License URL : https://www.monetplus.cz/

URI scheme

BasePath : /mep-iam-mock

Tags

  • case-controller : IAM Controller for Case
  • iam-controller : IAM Controller (for MEP)
  • ping-controller : Health Check IAM Controller

Paths

notifyInstanceStateChange

Instance state changed notification

POST /iam/v1/iam4case/notifyInstanceStateChanged

Description

Service is called when new instance is activated or deactivated (using mobile phone or when expired); if state change is performed by explicit call on CASE (e.g. deactivateInstance), notification is not called

Parameters

Type Name Description Schema
Header X-TRN-ID
required 		Unique identifier of executed operation. It is recommended to write this identifier to operating logs, it serves as a correlation identifier. string
Body request
required 		NotifyInstanceStateChangedRequest NotifyInstanceStateChangedRequest

Responses

HTTP Code Description Schema
200 OK SuccessResponse
400 Fail or Error Response ErrorResponse
500 Internal Server Error No Content
503 Service Unavailable No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • case-controller

Example HTTP request

Request path
/iam/v1/iam4case/notifyInstanceStateChanged
Request header
"string"
Request body
{
  "instanceInfo" : {
    "activityContext" : {
      "ipAddress" : "string",
      "threatFlags" : "string",
      "geoLocation" : {
        "latitude" : 0.0,
        "longitude" : 0.0
      }
    },
    "blockedUntil" : "2017-01-01T12:00:00Z",
    "expireTime" : "2018-01-01T12:00:00Z",
    "methodType" : "string",
    "instanceId" : "string",
    "instanceState" : "string"
  },
  "muid" : "demo"
}

Example HTTP response

Response 200
{
  "status" : "success"
}
Response 400
{
  "status" : "error",
  "code" : 1001,
  "message" : "Error by specification"
}

notifyMethodStateChange

Method state changed notification

POST /iam/v1/iam4case/notifyMethodStateChanged

Description

Service is called in case of blocking method with wrong attempts. If method state change is performed by explicit call on CASE (e.g. blockMethod), notification is not sent back to IAM. Also service is not called when temporary blocking expires (for temporary blocking there is notification sent with information about blocking time when the the block happens).

Parameters

Type Name Description Schema
Header X-TRN-ID
required 		Unique identifier of executed operation. It is recommended to write this identifier to operating logs, it serves as a correlation identifier. string
Body notifyMethodStateChangedRequest
required 		NotifyMethodStateChangedRequest NotifyMethodStateChangedRequest

Responses

HTTP Code Description Schema
200 OK SuccessResponse
400 Fail or Error Response ErrorResponse
500 Internal Server Error No Content
503 Service Unavailable No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • case-controller

Example HTTP request

Request path
/iam/v1/iam4case/notifyMethodStateChanged
Request header
"string"
Request body
{
  "methodInfo" : {
    "blockedUntil" : "2017-01-01T12:00:00Z",
    "expireTime" : "2018-01-01T12:00:00Z",
    "methodState" : "string",
    "methodType" : "string"
  },
  "muid" : "demo"
}

Example HTTP response

Response 200
{
  "status" : "success"
}
Response 400
{
  "status" : "error",
  "code" : 1001,
  "message" : "Error by specification"
}

notifyTransactionStateChanged

Transaction state changed notification

POST /iam/v1/iam4case/notifyTransactionStateChanged

Description

Service is called at user action of confirm / reject transaction using mobile device or when last wrong attempt will block method (and cause transaction could not be confirmed); when BE cancels transaction (calling cancelTransaction), when it is expired or confirmed with calling service verifyTransactionCode, the notification is not called.

Parameters

Type Name Description Schema
Header X-TRN-ID
required 		Unique identifier of executed operation. It is recommended to write this identifier to operating logs, it serves as a correlation identifier. string
Body notifyTransactionStateChangedRequest
required 		NotifyTransactionStateChangedRequest NotifyTransactionStateChangedRequest

Responses

HTTP Code Description Schema
200 OK SuccessResponse
400 Fail or Error Response ErrorResponse
500 Internal Server Error No Content
503 Service Unavailable No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • case-controller

Example HTTP request

Request path
/iam/v1/iam4case/notifyTransactionStateChanged
Request header
"string"
Request body
{
  "caseId" : "xBrvtpAW+slBUmhIBg8t9tM3WHQ2u0Z3eFQY88uHoYnfB0YcsvgLEPTvO2WB2WMRGeRoXmUEIeTcQnApAEZsDNAz/SAwKGm8meMMbvFpHfHkuJJu+YjUI/+AHh/uaMav",
  "muid" : "demo",
  "notificationDestination" : "ntf-rcv-1",
  "transactionState" : "string"
}

Example HTTP response

Response 200
{
  "status" : "success"
}
Response 400
{
  "status" : "error",
  "code" : 1001,
  "message" : "Error by specification"
}

sendMessage

Send message

POST /iam/v1/iam4case/sendMessage

Description

Send message through defined channel to defined contact.

Parameters

Type Name Description Schema
Header X-TRN-ID
required 		Unique identifier of executed operation. It is recommended to write this identifier to operating logs, it serves as a correlation identifier. string
Body sendMessageRequest
required 		SendMessageRequest SendMessageRequest

Responses

HTTP Code Description Schema
200 OK. In channel enumeration value ANY is not returned. SendMessageResponse
400 Fail or Error Response ErrorResponse
500 Internal Server Error No Content
503 Service Unavailable No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • case-controller

Example HTTP request

Request path
/iam/v1/iam4case/sendMessage
Request header
"string"
Request body
{
  "channel" : "string",
  "destination" : {
    "type" : "string",
    "value" : "[email protected]"
  },
  "message" : {
    "locale" : {
      "country" : "string",
      "displayCountry" : "string",
      "displayLanguage" : "string",
      "displayName" : "string",
      "displayScript" : "string",
      "displayVariant" : "string",
      "extensionKeys" : [ { } ],
      "iso3Country" : "string",
      "iso3Language" : "string",
      "language" : "string",
      "script" : "string",
      "unicodeLocaleAttributes" : [ "string" ],
      "unicodeLocaleKeys" : [ "string" ],
      "variant" : "string"
    },
    "template" : "string",
    "text" : "Zpráva k odeslání"
  }
}

Example HTTP response

Response 200
{
  "data" : {
    "channel" : "string",
    "destination" : {
      "type" : "string",
      "value" : "[email protected]"
    }
  },
  "status" : "success"
}
Response 400
{
  "status" : "error",
  "code" : 1001,
  "message" : "Error by specification"
}

aliases

Get aliases (optionally for chosen realm)

GET /iam/v1/iam4mep/aliases

Description

Service returns known aliases for MUID within particular realm.

Parameters

Type Name Description Schema
Header X-TRN-ID
required 		Unique identifier of executed operation. It is recommended to write this identifier to operating logs, it serves as a correlation identifier. string
Query muid
required 		Unique identity identifier. Required parameter. string
Query realm
optional 		Realm identifier.Returns all aliases of all realms if not specified. string

Responses

HTTP Code Description Schema
200 OK GetAliasesResponse
400 Fail or Error Response ErrorResponse
500 Internal Server Error No Content
503 Service Unavailable No Content

Consumes

  • \*/*

Produces

  • application/json

Tags

  • iam-controller

Example HTTP request

Request path
/iam/v1/iam4mep/aliases?muid=string
Request header
"string"

Example HTTP response

Response 200
{
  "data" : {
    "aliases" : [ {
      "alias" : "string",
      "realm" : "string",
      "type" : "string"
    } ]
  },
  "status" : "success"
}
Response 400
{
  "status" : "error",
  "code" : 1001,
  "message" : "Error by specification"
}

identity

Get identity information

POST /iam/v1/iam4mep/identity

Description

Service returns defined set of information about identity.

Parameters

Type Name Description Schema
Header X-TRN-ID
required 		Unique identifier of executed operation. It is recommended to write this identifier to operating logs, it serves as a correlation identifier. string
Body request
required 		request GetIdentityRequest

Responses

HTTP Code Description Schema
200 OK GetIdentityResponse
400 Fail or Error Response ErrorResponse
500 Internal Server Error No Content
503 Service Unavailable No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • iam-controller

Example HTTP request

Request path
/iam/v1/iam4mep/identity
Request header
"string"
Request body
{
  "alias" : {
    "alias" : "string",
    "realm" : "string",
    "type" : "string"
  },
  "applicationIdHint" : "APP_ID_HINT",
  "identityStatusRequired" : false,
  "requiredAttributes" : [ "string" ],
  "requiredMethods" : [ "string" ],
  "requiredScopes" : [ "string" ]
}

Example HTTP response

Response 200
{
  "data" : {
    "identity" : {
      "attributes" : [ {
        "type" : "string",
        "value" : "string"
      } ],
      "grantedScopes" : [ "string" ],
      "identityState" : "string",
      "methodInfoArray" : [ {
        "blockedUntil" : "2017-01-01T12:00:00Z",
        "expireTime" : "2018-01-01T12:00:00Z",
        "methodState" : "string",
        "methodType" : "string"
      } ],
      "muid" : "string"
    }
  },
  "status" : "success"
}
Response 400
{
  "status" : "error",
  "code" : 1001,
  "message" : "Error by specification"
}

ping

IAM service ping (optionally with all dependencies)

GET /iam/v1/ping

Description

Verifies IAM services availability on a particular node. (This service is exposed as others on secured port (TLS connection - https) and also it is exposed on an open port for http request from load balancer.)

Parameters

Type Name Description Schema
Header X-TRN-ID
optional 		Unique identifier of executed operation. It is recommended to write this identifier to operating logs, it serves as a correlation identifier.
It is presumed it will not be used for ping.		 string
Query checkDependentComponents
optional 		True if is is required to also check availability of dependant components (e.g. DB, SMS gateway, etc.).False / not filled - do not check availability of dependant components. boolean

Responses

HTTP Code Description Schema
200 OK SuccessResponse
400 Fail or Error Response ErrorResponse
500 Internal Server Error No Content
503 Service Unavailable No Content

Consumes

  • \*/*

Produces

  • application/json

Tags

  • ping-controller

Example HTTP request

Request path
/iam/v1/ping
Request header
"string"

Example HTTP response

Response 200
{
  "status" : "success"
}
Response 400
{
  "status" : "error",
  "code" : 1001,
  "message" : "Error by specification"
}

Definitions

ActivityContext

Name Description Schema
geoLocation
required 		Example : "[geolocation](#geolocation)" GeoLocation
ipAddress
required 		Example : "string" string
threatFlags
required 		Example : "string" string

Alias

Name Description Schema
alias
optional 		Example : "string" string
realm
optional 		Example : "string" enum (INTERNAL, OP_GOOGLE, OP_FACEBOOK, OP_LINKEDIN, OP_MOJEID, EIDAS_NIA)
type
optional 		Example : "string" enum (MUID, USERNAME, EMAIL, X509_SUBJ, SAM_ACCOUNT_NAME, USER_PRINCIPAL_NAME, TELEPHONE_NUMBER, GUID, OPC_SUBJ, X509_CERT, KERBEROS_PRINCIPAL_NAME)

AliasData

Required attribute of JSend envelope for 'success' and 'fail' status.

Name Description Schema
aliases
required 		Alias structure conatins alias type and its value.
Example : [ "[alias](#alias)" ] 		< Alias > array

Attribute

Name Description Schema
type
optional 		Example : "string" enum (SUBJECT, NAME, GIVEN_NAME, FAMILY_NAME, MIDDLE_NAME, NICKNAME, PREFERRED_USERNAME, PROFILE, PICTURE, WEBSITE, EMAIL, EMAIL_VERIFIED, GENDER, BIRTHDATE, ZONEINFO, LOCALE, PHONE_NUMBER, PHONE_NUMBER_VERIFIED, ADDRESS, UPDATED_AT, EMPLOYEE_ID, ACTIVATION_CHANNEL)
value
optional 		Example : "string" string

Character

Type : object

ErrorResponse

Name Description Schema
code
optional 		Numerical error code by EA.
Example : 1001 		integer (int32)
message
optional 		Error description (e.g. SMS sending service not available).
Example : "Error by specification" 		string
status
required 		Required attribute of JSend envelope
Example : "error" 		enum (error)

GeoLocation

Name Description Schema
latitude
required 		Example : 0.0 number (double)
longitude
required 		Example : 0.0 number (double)

GetAliasesResponse

Name Description Schema
data
optional 		Example : "[aliasdata](#aliasdata)" AliasData
status
required 		Required attribute of JSend envelope
Example : "success" 		enum (success)

GetIdentityRequest

Name Description Schema
alias
required 		Example : "[alias](#alias)" Alias
applicationIdHint
optional 		Application identifier in which context is request called. Parameter is passed only when it is known in application context. IAM can process request based on knowledge of application context. Parameter is typically passed from federation processes, CASE do not pass this parameter.
Example : "APP_ID_HINT" 		string
identityStatusRequired
optional 		It is required that output contains information of identity state.Optional parameter - if not passed, identity state information is not required.
Example : false 		boolean
requiredAttributes
optional 		It is required that output contains attributes stated in array. IAM passes only known values. Optional parameter - if not passed, no attributes are required.
Example : [ "string" ] 		< enum (SUBJECT, NAME, GIVEN_NAME, FAMILY_NAME, MIDDLE_NAME, NICKNAME, PREFERRED_USERNAME, PROFILE, PICTURE, WEBSITE, EMAIL, EMAIL_VERIFIED, GENDER, BIRTHDATE, ZONEINFO, LOCALE, PHONE_NUMBER, PHONE_NUMBER_VERIFIED, ADDRESS, UPDATED_AT, EMPLOYEE_ID, ACTIVATION_CHANNEL) > array
requiredMethods
optional 		It is required that output contains information of method states given in array. IAM passes only known values. Optional parameter - if not passed, no method information are required.
Example : [ "string" ] 		< enum (PASSWORD, ACTIVATION_CODE, SMS, CM) > array
requiredScopes
optional 		Scopes/roles list which have to be checked for given identity. Optional parameter - if not passed, it is expected returning of all roles available in call context for given identity.
Example : [ "string" ] 		< string > array

GetIdentityResponse

Name Description Schema
data
optional 		Example : "[identitydata](#identitydata)" IdentityData
status
required 		Required attribute of JSend envelope
Example : "success" 		enum (success)

Identity

Name Description Schema
attributes
optional 		Identity attributes. Returned only if it was requested. Empty array is returned in case that none of requested attributes are not known.
Example : [ "[attribute](#attribute)" ] 		< Attribute > array
grantedScopes
optional 		Scopes/roles list available in request context for given identity. If input set of requiredScopes was passed, then set of grantedScopes should not contain roles/scopes, which was not requested in input set.Empty array is returned in case that none of requested scopes/roles are available.
Example : [ "string" ] 		< string > array
identityState
optional 		Identity state.Returned only if it was requested.
Example : "string" 		enum (ACTIVE, BLOCKED, DISABLED, EXPIRED)
methodInfoArray
optional 		Information about requested methods of identity. Returned only if it was requested. Empty array is returned in case that none of requested methods are not known.
Example : [ "[methodinfo](#methodinfo)" ] 		< MethodInfo > array
muid
optional 		Identity's MUID.
Example : "string" 		string

IdentityData

Required attribute of JSend envelope for 'success' and 'fail' status.

Name Description Schema
identity
optional 		Example : "[identity](#identity)" Identity

InstanceInfo

Name Description Schema
activityContext
optional 		Example : "[activitycontext](#activitycontext)" ActivityContext
blockedUntil
optional 		format: ISO 8601 (Java 8, JSR 310)
Example : "2017-01-01T12:00:00Z" 		string (date-time)
expireTime
optional 		format: ISO 8601 (Java 8, JSR 310)
Example : "2018-01-01T12:00:00Z" 		string (date-time)
instanceId
required 		Example : "string" string
instanceState
required 		Example : "string" enum (ACTIVE, BLOCKED_MAN, DEACTIVATED, EXPIRED, INITIATED)
methodType
required 		Example : "string" enum (PASSWORD, ACTIVATION_CODE, SMS, CM)

Locale

Name Description Schema
country
optional 		Example : "string" string
displayCountry
optional 		Example : "string" string
displayLanguage
optional 		Example : "string" string
displayName
optional 		Example : "string" string
displayScript
optional 		Example : "string" string
displayVariant
optional 		Example : "string" string
extensionKeys
optional 		Example : [ "[character](#character)" ] < Character > array
iso3Country
optional 		Example : "string" string
iso3Language
optional 		Example : "string" string
language
optional 		Example : "string" string
script
optional 		Example : "string" string
unicodeLocaleAttributes
optional 		Example : [ "string" ] < string > array
unicodeLocaleKeys
optional 		Example : [ "string" ] < string > array
variant
optional 		Example : "string" string

Message

Name Description Schema
locale
required 		Required message localization.
Example : "[locale](#locale)" 		Locale
template
required 		Template identifier. Defines template used for message formatting. Another templates could be defined when needed (especially when using FS FTA).
Example : "string" 		enum (DIRECT, AUTHENTICATION_OTP, ACTIVATION_CODE, ACTIVATION_CHECK_CODE)
text
required 		Code value itself.
Example : "Zpráva k odeslání" 		string

MessageDestination

Name Description Schema
type
required 		Example : "string" enum (EMAIL, PHONE_NUMBER, MUID, ADDRESS)
value
optional 		Example : "[email protected]" string

MethodInfo

Name Description Schema
blockedUntil
optional 		format: ISO 8601 (Java 8, JSR 310)
Example : "2017-01-01T12:00:00Z" 		string (date-time)
expireTime
optional 		format: ISO 8601 (Java 8, JSR 310)
Example : "2018-01-01T12:00:00Z" 		string (date-time)
methodState
optional 		Example : "string" enum (ACTIVE, BLOCKED_MAN, BLOCKED_USAGE_TEMP, BLOCKED_USAGE_PERM, DEACTIVATED)
methodType
optional 		Example : "string" enum (PASSWORD, ACTIVATION_CODE, SMS, CM)

NotifyInstanceStateChangedRequest

Name Description Schema
instanceInfo
required 		Example : "[instanceinfo](#instanceinfo)" InstanceInfo
muid
required 		Identity's MUID.
Example : "demo" 		string

NotifyMethodStateChangedRequest

Name Description Schema
methodInfo
required 		Example : "[methodinfo](#methodinfo)" MethodInfo
muid
required 		Identity's MUID.
Example : "demo" 		string

NotifyTransactionStateChangedRequest

Name Description Schema
caseId
required 		Transaction identifier
Example : "xBrvtpAW+slBUmhIBg8t9tM3WHQ2u0Z3eFQY88uHoYnfB0YcsvgLEPTvO2WB2WMRGeRoXmUEIeTcQnApAEZsDNAz/SAwKGm8meMMbvFpHfHkuJJu+YjUI/+AHh/uaMav" 		string
muid
optional 		Identity's MUID.
This parameter do not have to be passed always. If IAM needs to know user's context, it should map it to caseId at transaction initiation.
Example : "demo" 		string
notificationDestination
optional 		Target for sending notification
Example : "ntf-rcv-1" 		string
transactionState
required 		Transaction states
Example : "string" 		enum (INITIATED, LOADED, EXPIRED, AUTHORIZED, FAILED, CANCELED)

SendMessageData

Required attribute of JSend envelope for 'success' and 'fail' status.

Name Description Schema
channel
required 		Channel required for sending message. Defines required channel for sending message.
Example : "string" 		enum (SMS, EMAIL, LETTER, ANY)
destination
required 		Example : "[messagedestination](#messagedestination)" MessageDestination

SendMessageRequest

Name Description Schema
channel
required 		Channel required for sending message. Defines required channel for sending message.
Example : "string" 		enum (SMS, EMAIL, LETTER, ANY)
destination
required 		Example : "[messagedestination](#messagedestination)" MessageDestination
message
required 		Example : "[message](#message)" Message

SendMessageResponse

Name Description Schema
data
optional 		Example : "[sendmessagedata](#sendmessagedata)" SendMessageData
status
required 		Required attribute of JSend envelope
Example : "success" 		enum (success)

SuccessResponse

Name Description Schema
status
required 		Required attribute of JSend envelope
Example : "success" 		enum (success)
⚠️ **GitHub.com Fallback** ⚠️