API Access Control

General concept of OAuth2 supports user rights and data protection regulation in GDPR and similar international regulations (US: CCPA; Japan: PPI)

OAuth2 framework is a user-centric protocol for access delegation to ensure regulatory compliant usage of SMA APIs and provides authorization flows to support the desire of individual users to control how their information is processed. OAuth2 allows 3rd party applications to request limited access to an HTTP service, either on behalf of a SMA resource owner or by allowing the 3rd party application to obtain access on its own behalf. Access is requested by the client/application, which can be a website, desktop application or a mobile application.

According to regulations, SMA resource owners will have to provide their explicit, revocable (and logged) user consent to share data from SMA to 3rd party applications. 3rd party applications will request data access detailed by scopes of a given resource owner, and the SMA user has to provide his consent for such requests. Users are entitled to revoke their consents at any time.

OAuth2 defines 4 logical roles to enable the authorization flows for access delegation:

  • Resource owner: SMA user eligible to grant access to his data (protected resources)
  • Authentication provider: SMA OAuth2 server
  • Resource server: SMA API server which requires an access token and validates token scopes
  • Client application: 3rd party application, SMA registered and authenticated by SMA clientCredentials, requesting an access token with some scopes

Recommendation: Please encourage plant owners to create a SMA user account to manage their 3rd party permissions for full compliance to data privacy regulations. In most cases an installer/operator will not be eligible for access delegation on behalf of the plant owner. Furthermore, a SMA plant owner account will enable the user for consumer-centric use-cases such as enabling smartHome or eMobility Apps to access his SMA plant data.

3rd party application use-cases and according OAuth2 authorization flows

In order to setup your SMA API Key, you must select the appropriate authorization flow for your use-case. Please make sure that you provide all relevant clientData as defined in the SMA API contract.

O&M Systems

Off-Screen user

  • Resource owner is not present
  • Off-screen 3rd party app, e.g. O&M or Scade-system

Agent/app initiates an access-request to a SMA user, who is off-screen. SMA will notify the user to trigger a user decision on the asynchronous request.

Custom authorization flow

SMA Monitoring-API

End-user Apps & Portals

On-Screen user

  • Resource owner is present
  • On-screen 3rd party app, e.g. SmartHome or eMobility App

SMA resource owner initiates the flow in the 3rd party app, authenticates at SMA (userLogin) and immediately decides on access–request.

OAuth2 Authorization Code grant flow

SMA Monitoring-API

Special purpose

No user: anonymized data

  • No resource owner involved
  • 3rd party app gets PV-forecasts, e.g. eMobility App

No consent flow needed as no resource owner is directly linked to provided data.

OAuth2 Client Credentials grant flow

SMA GeoForecast-API

SMA API Access Control
SMA user consent for 3rd party apps

Download PDF

OAuth2 Authorization Code Grant Flow

To enable a 3rd party eMobility or Smart Home application to retrieve SMA data e.g. via SMA Monitoring-API of an on-screen SMA user, you will need to implement the OAuth2 authorization code grant flow as described here.

The authorization code grant type is used to obtain both access tokens and refresh tokens from the SMA authorization server and is optimised for confidential clients. Since this is a redirection-based flow, the client MUST be capable of interacting with the SMA user-agent (typically a web browser) and be capable of receiving incoming requests (via redirection) from the authorization server.

In the authorization code grant flow, the client needs to perform two steps to obtain the tokens, involving the browser in the first step and a back-channel request in the second step.

  Step1 Step2
Purpose a. Authenticate the SMA resource owner/user
b. Authorise the 3rd party client application
a. Authenticate the 3rd party client application
b. Exchange "code" for "token"
Via Front-channel request Back-channel request
To SMA Authorization endpoint
Sandbox: sandbox.smaapis.de/oauth2/auth
Productive: auth.smaapis.de/oauth2/auth
SMA Token endpoint
Sandbox: sandbox.smaapis.de/oauth2/token
Productive: auth.smaapis.de/oauth2/token
Result on success Authorization code
(as input parameter for step2)
Access Token
Refresh Token

 

Step1: Authorization request

The client application initiates the flow by redirecting the browser to the SMA authorization server with an authorization request which includes the following parameters and encoded as application/x-www-form-urlencoded as defined here.

Sample request

GET auth.smaapis.de/oauth2/auth?
client_id={yourClientID}&
client_secret=={yourClientSecret}&
response_type={code}&
redirect_uri={clientRedirectURI/callback}&
state={opaque_value}

Parameters

  • client_id: Value MUST be set according to Id provided by SMA
  • client_secret: Value MUST be set according to secret provided by SMA
  • response_type: Value MUST be set to code
  • redirect_uri: Value MUST be set as defined on application registration form
  • scope: SMA will not make use of the optional OAuth2 scopes initially. Thus the 3rd party authorization is requesting access to all (API) resources of a given SMA user (privileges).
  • state: Value MUST be set. An opaque value your application adds to the initial request, which the authorization server includes when redirecting back to your application URI.

SMA authorization request processing

SMA authorization server validates the request to ensure that all required parameters are present and valid. If the request is valid, the authorization server authenticates the resource owner - either there is a valid session established by a browser cookie or by prompting the user to login. After that, the server will determine if the client is to be authorized or not, by asking the user for his permission on the user consent page.

When a user decision is established, the authorization server respond by redirecting the user back to the client URI along with an authorization code and the formerly provided state (opaque value) from the client request in the query string.

SMA developer portal user consent sample

Sample response (success)

https://yourapp.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj

Your client application must validate the state parameter, and use the code to proceed to the next step.

Step2: Access token request (Exchange "code" for "token")

The authorization code is an intermediate credential, which encodes the authorization obtained at step 1. It is therefore opaque to the client and only has meaning to the authorization server. To retrieve the access token for the API endpoint, the client app must submit the code to the authorization server, but this time with a direct back-channel request.

This is done for two reasons:

  • To authenticate confidential clients with the authorization server before revealing the token;
  • To deliver the token straight to the client preventing cross-site forgery by avoiding exposing it to the browser.

Sample request

POST auth.smaapis.de/oauth2/token
HTTP/1.1
Host: smaapis.de
Content-Type: application/x-www-form-urlencoded

client_id={yourClientID}&client_secret=={yourClientSecret}&
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https://yourapp.example.com

Parameters

  • client_id: Value MUST be set according to Id provided by SMA
  • client_secret: Value MUST be set according to secret provided by SMA
  • grant_type: Value MUST be set to “authorization_code
  • redirect_uri: Value MUST be set as defined on application registration form

On success the authorization server will return a JSON object with the issued access and refresh token:

Sample response (success)

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":”300”,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}

  • token_type: bearer token means that the bearer can access authorized resources without further identification. Short lifespan for improved security. When the access token expires, the user must (re-)authenticate again to get a new access token. Once issued, this token_type cannot be revoked.
  • expires_in: value in seconds: 300 seconds = 5 minutes
  • refresh_token: long-lived token type, expires after 30 days and is used to obtain new access tokens without the user's interaction. Refresh tokens extend the connection to the user's account, while still allowing revokeability. If the user has revoked access to the 3rd party application, the refresh token is no longer valid.

A new access token can be obtained by using grant_type "refresh_token"

Sample request (refresh token)

POST auth.smaapis.de/oauth2/token
HTTP/1.1
Host: smaapis.de
Content-Type: application/x-www-form-urlencoded

client_id={yourClientID}&client_secret={yourClientSecret}&
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Custom OAuth2-oriented Authorization Flow

To enable a 3rd party application to retrieve SMA data, e.g. via SMA Monitoring-API of an off-screen SMA user, you will need to implement the custom authorization flow as described here.

SMA combines the standard oAuth2 client credential grant type illustrated in step1 with a custom backchannel user-authorization as explained in step2 / step3.

To improve the SMA developer experience we have enhanced the /bc-authorize endpoints so that a job-administration for the asynchronous user-consent requests to ResourceOwners become obsolet. The former v1-endpoints will remain to be active for the time being.

In the custom authorization grant flow, the client needs to perform three steps to gain access to a user´s resources.

  Step1 Step2 Step3
Purpose a. Authenticate the 3rd Party Client
b. Authorize the 3rd party client app for specified SMA APIs
a. Authenticate the SMA resource user
b. Authorize the 3rd party client application
a. Authenticate the 3rd party client app
b. Poll result for “user” (SystemOwner)
Via Back-channel request Back-channel request Back-channel request
To SMA Authorization endpoints
Sandbox: POST sandbox.smaapis.de/oauth2/token
Productive: POST auth.smaapis.de/oauth2/token
SMA BC-Auth endpoints
Sandbox: POST sandbox.smaapis.de/oauth2/v2/bc-authorize
Productive: POST async-auth.smaapis.de/oauth2/v2/bc-authorize
SMA BC-Auth endpoints
Sandbox: GET sandbox.smaapis.de/oauth2/v2/bc-authorize/{loginHint}
Productive: GET async-auth.smaapis.de/oauth2/v2/bc-authorize/{loginHint}
Result on success (Client) Token Authorization Request Identifier User permits access;
Client can access user resources

 

Step1: Client authorization request

As a pre-requisit for the custom flow, your client app will need to request a (Client)Token from the SMA authorization server which includes the following parameters and encoded as application/x-www-form-urlencoded as defined here.

Sample request

POST auth.smaapis.de/oauth2/token
HTTP/1.1
Host: smaapis.de
Content-Type: application/x-www-form-urlencoded

client_id={yourClientID}&client_secret={yourClientSecret}&
grant_type=client_credentials

Parameters

  • client_id: Value MUST be set according to Id provided by SMA
  • client_secret: Value MUST be set according to secret provided by SMA
  • grant_type: Value MUST be set to “client_credentials”

Sample response (success)

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
      "access_token":"2YotnFZFEjr1zCsicMWpAA",
      "token_type":"bearer",
      "expires_in":”300”,
      "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}

 

Step2: Resource-owner authorization request

Once the ClientToken has been obtained it can be used to make calls to the SMA backchannel-authorization endpoint by passing it as a Bearer Token in the Authorization header of the HTTP-request. If the request client authentication failed or is invalid, the authorization server returns an error response.

Sample request

POST async-auth.smaapis.de/oauth2/v2/bc-authorize
HTTP/1.1
Host: smaapis.de
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1...
{
     loginHint: {emailAddressResourceOwner}
}

Parameters

  • loginHint: Value MUST be set in order to address the resource owner via email.
    Please assure that SMA user has previously got assigned “systemOwner” flag on the specific PV-systems via SMA Portal UIs.

Sample response (success)

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

     "loginHint": “max.mustermann@sma.de",
     "state": "PENDING”,
     "expirationDate": "2020-09-30T11:37:35.1300000Z",
     "interval": 1800
}

Parameters

  • loginHint: eMail address of SMA user (systemOwner) who should receive the access request of your 3rd party application.
  • state: Following states are possible: PENDING, ACCEPTED, REJECTED, EXPIRED, REVOKED.
  • expirationDate: Expiration date of the request. Currently, we foresee 7 day to allow resource-owner to provide his consent. After this time, request will be considered expired and the “state” value will change accordingly to “expired”.
  • interval: Minimum amount of time in seconds that the client SHOULD wait between polling requests to the token endpoint. Currently we foresee 30 minutes before you SHOULD start polling.

SMA authorization request processing (out of band)

SMA authorization server validates the request to ensure that the client is authenticated and all required parameters are present and valid. If the request is valid, the authorization server will notify the SMA resource owner by eMail and inform him about your clients´ access request on his resources. This eMail will include a link to prompt the user login (user authentication) and present the user consent screen as for the code grant flow.

When a user decision is established, the SMA authorization server will remember the user decision and update the status of the related authorization request.

Step3: Resource-owner authorization decision

In order to successfully access specific user data on SMA resource endpoints, loginHint must carry the status “ACCEPTED”. Your client must start polling against the SMA bc-authorization endpoint with the specific loginHint.

Sample request

GET async-auth.smaapis.de/oauth2/v2/bc-authorize/{loginHint}
HTTP/1.1
Host: smaapis.de
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1...

Sample response (Status: “ACCEPTED”)

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
     “loginHint”: “max.mustermann@sma.de”,
     “state”: “PENDING”,
     “expirationDate”: "2020-09-30T11:37:35.1300000Z",
     “interval”: 1800
}

Parameters

In case the resource owner…

  • has not yet decided on your access request, our server will return a reply with status "PENDING"
  • has confirmed your access request, our server will return a reply with status "ACCEPTED"
  • has declined your access request, our server will return a reply with status "REJECTED"
  • has not taken any actions on 7 consecutive days, it is assumed that the request has been lost, the job will be terminated and status "EXPIRED" will be returned
  • has actively revoked his user consent for your application, our server will return a reply with status "REVOKED"

Access to the Ressource API (Use of access token in API-endpoint/resource requests)

Once the access token has been obtained it can be used to make calls to the SMA resource server by passing it as a Bearer Token in the Authorization header of the HTTP-request. If the request client authentication failed or is invalid, the authorization server returns an error response.

Sample request

"securityDefinitions":
{
      "authenticationBearer":
      "name": "Authorization",
      "in": "header",
      "description": "Clients authentication bearer token to authenticate itself to the API.",
      "type": "apiKey"
}

We will be happy to advise you on your API projects.

We will be happy to advise you on your API projects.

Contact us