Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

Overview

This service provides a SOAP alternative to the RESTful oauth2token  service, and is used to acquire an OAuth 2 Token that can be used by an OAuth 2 Authenticated User of a Client App for access to Projector services.  Note that this service should not be provided with a SessionTicket on invocation.  Note also that if the response has a non-null value for RedirectUrl , the service was invoked on the incorrect server and must be re-invoked on the server specified in RedirectUrl .

Request Format


PwsAcquireOauth2Token Request
  • PwsAcquireOauth2Token

Request Elements


Element

Data Type

Required?

Default

Description

Sample Data

RequestId

Int32

No


Click here for more information


SessionTicket

String

No


Should be omitted or set to null.


ClientIdentifier

String

Yes


Guid string that identifies the client app requesting a token

24748faf-e239-d132-167a-6e4d3e1bd0fb

ClientSecret

String

Yes


Secret string that client app uses to prove itself

r6tuVhR3ol1BFFVfy3Oe-J8VoH0KpkgLVqAMi-IIgvd_Lr613IEYcXhKAea8eLtQKSIgQ4jHIKhCKQcwriUtgB

Code

String

When GrantType="code"


The short-lived authentication code that was provided on the successful redirect of the oauth2authorize  request.  Must be supplied if GrantType="code" and may not be supplied for any other GrantType.

E2BgYJjLoNrEY50z-8hLMXevukfd3EWpZcn5RQW6xemGeYelfl_aetMDAA

CodeVerifier

String

No


Code Verifier generated by the client app and for which a code challenge was previously sent as part of the oauth2authorize  request that was implementing PKCE.  May only be supplied if GrantType="code", and must be supplied if a code challenge was part of the authorization request that generated the code.

swubMxS7yR-SYjlEwuu5gaS8~bvgL-ngbpZiYFLR_4Vf~u388c.qimhmm6kVc3h3h~TSmhDj02AIPeGcI_Y

GrantType

String

Yes


Currently must be either "code" for an initial grant, or "refresh_token" for a token refresh.


RedirectUri

String

When GrantType="code"


Must be identical to the redirect_uri  that was supplied as part of the oauth2authorize  request.

https://my.app.com/redirect-handler

RefreshToken

String

When GrantType="refresh_token"


A valid refresh token that designates a client app connection needing a refresh

E2BgYJjLoNrEY50z-7gMN1evukfd3EWpZcn5RQW6xemGeYelfl_aetMDAA

Request Usage Example(s)

Request for OAuth 2 Token on initial authentication grant by code 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pws="http://projectorpsa.com/PwsProjectorServices/" xmlns:req="http://projectorpsa.com/DataContracts/Requests/">
   <soapenv:Header/>
   <soapenv:Body>
      <pws:PwsAcquireOauth2Token>
         <pws:serviceRequest>
            <req:ClientIdentifier>24748faf-e239-d132-167a-6e4d3e1bd0fb</req:ClientIdentifier>
            <req:ClientSecret>r6tuVhR3ol1BFFVfy3Oe-J8VoH0KpkgLVqAMi-IIgvd_Lr613IEYcXhKAea8eLtQKSIgQ4jHIKhCKQcwriUtgB</req:ClientSecret>
            <req:Code>E2BgYJjLoNrEY50z-8hLMXevukfd3EWpZcn5RQW6xemGeYelfl_aetMDAA</req:Code>
            <req:CodeVerifier>swubMxS7yR-SYjlEwuu5gaS8~bvgL-ngbpZiYFLR_4Vf~u388c.qimhmm6kVc3h3h~TSmhDj02AIPeGcI_Y</req:CodeVerifier>
            <req:GrantType>code</req:GrantType>
            <req:RedirectUri>https://my.app.com/redirect-handler</req:RedirectUri>
         </pws:serviceRequest>
      </pws:PwsAcquireOauth2Token>
   </soapenv:Body>
</soapenv:Envelope>
Request for OAuth2 Token Refresh 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pws="http://projectorpsa.com/PwsProjectorServices/" xmlns:req="http://projectorpsa.com/DataContracts/Requests/">
   <soapenv:Header/>
   <soapenv:Body>
      <pws:PwsAcquireOauth2Token>
         <pws:serviceRequest>
            <req:ClientIdentifier>24748faf-e239-d132-167a-6e4d3e1bd0fb</req:ClientIdentifier>
            <req:ClientSecret>r6tuVhR3ol1BFFVfy3Oe-J8VoH0KpkgLVqAMi-IIgvd_Lr613IEYcXhKAea8eLtQKSIgQ4jHIKhCKQcwriUtgB</req:ClientSecret> 
            <req:GrantType>refresh_token</req:GrantType>
            <req:RefreshToken>E2BgYJjLoNrEY50z-7gMN1evukfd3EWpZcn5RQW6xemGeYelfl_aetMDAA</req:RefreshToken>
         </pws:serviceRequest>
      </pws:PwsAcquireOauth2Token>
   </soapenv:Body>
</soapenv:Envelope>


Response Format


PwsAcquireOauth2Token Response
  • PwsAcquireOauth2TokenResponse
    • PwsAcquireOauth2TokenResult: PwsAcquireOauth2TokenRs
      • Messages: PwsMessage[]
      • ResponseId: Int32
      • Status: RequestStatus
      • ServerTimestampUtc: DateTime
      • AccessToken: String
      • ExpiresInSeconds: Int32
      • MaxLifetimeMinutes: Int32
      • RedirectUrl: String
      • RefreshToken: String
      • RestServiceAuthority: String
      • SoapServiceAuthority: String
      • TimeoutMinutes: Int32
      • TokenType: String
      • Scope: String

Response Elements


Element

Data Type

Description

Sample Data

Messages

PwsMessage[]

The web service response status and message. Click here for more information.


ResponseId

Int32

Click here for more information


Status

RequestStatus

Click here for more information


ServerTimestampUtc

DateTime

Click here for more information


AccessToken

String

Token used for subsequent API access to Projector.  In practical terms, this is a SessionTicket.

Af4yzv6CcFKZEh2dz45zZg==

ExpiresInSeconds

Int32

How many seconds the AccessToken is valid for.

604800

MaxLifetimeMinutes

Int32

The maximum lifetime of the AccessToken in minutes.

10080

RedirectUrl

String

If this is set, this PwsAcquireOauth2Token  service invocation was made against the incorrect server for the user being authenticated.  If that is the case, the service should be re-invoked against this base URL.

https://secure2.projectorpsa.com

RefreshToken

String

The token that can be used to refresh the client app user's access when the Access Token is expired.

E2BgYJjLoNrEY50z-7gMN1evukfd3EWpZcn5RQW6xemGeYelfl_aetMDAA

RestServiceAuthority

String

The URL that must be used for any restful reporting services invoked with the AccessToken .

https://app2.projectorpsa.com

SoapServiceAuthority

String

The base URL that must be used for any SOAP services invoked with the AccessToken .

https://secure2.projectorpsa.com

TimeoutMinutes

Int32

How long the AccessToken  may be valid with no use in minutes.

10080

TokenType

String

projector_session_ticket 

projector_session_ticket
ScopeStringScope granted to this token, which may be fewer than those requested in the intitial authentication request, but never more.V:maintainCostCenters U:maintainUsers enterTime

Response Usage Example(s)

OAuth 2 Token Response when request is to correct server 
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <PwsAcquireOauth2TokenResponse xmlns="http://projectorpsa.com/PwsProjectorServices/">
         <PwsAcquireOauth2TokenResult xmlns:a="http://projectorpsa.com/DataContracts/Responses/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <Messages xmlns="http://projectorpsa.com/CommonServices/" xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/"/> 
            <ResponseId xmlns="http://projectorpsa.com/CommonServices/">0</ResponseId>
            <Status xmlns="http://projectorpsa.com/CommonServices/">Ok</Status>
            <ServerTimestampUtc xmlns="http://projectorpsa.com/CommonServices/">2021-12-08T15:50:51.1940528Z</ServerTimestampUtc>
            <a:AccessToken>Ab2C5oN9uZnVCAOt4STUaA==</a:AccessToken>
            <a:ExpiresInSeconds>604800</a:ExpiresInSeconds>
            <a:MaxLifetimeMinutes>10080</a:MaxLifetimeMinutes>
            <a:RedirectUrl i:nil="true"/>
            <a:RefreshToken>ASgA1_8QAAAAIv-lrk_NEdOPhr3ts0Ks2wtyZXZjb3JwLXNnMdXn_IJiutlI</a:RefreshToken>
            <a:RestServiceAuthority>http://app2.projectorpsa.com</a:RestServiceAuthority>
            <a:SoapServiceAuthority>http://secure2.projectorpsa.com</a:SoapServiceAuthority>
            <a:TimeoutMinutes>10080</a:TimeoutMinutes>
            <a:TokenType>projector_session_ticket</a:TokenType>
            <a:Scope/>
         </PwsAcquireOauth2TokenResult>
      </PwsAcquireOauth2TokenResponse>
   </s:Body>
</s:Envelope>
OAuth 2 Token Response when request is to incorrect server 
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <PwsAcquireOauth2TokenResponse xmlns="http://projectorpsa.com/PwsProjectorServices/">
         <PwsAcquireOauth2TokenResult xmlns:a="http://projectorpsa.com/DataContracts/Responses/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <Messages xmlns="http://projectorpsa.com/CommonServices/" xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/"/>  
            <ResponseId xmlns="http://projectorpsa.com/CommonServices/">0</ResponseId>
            <Status xmlns="http://projectorpsa.com/CommonServices/">Ok</Status>
            <ServerTimestampUtc xmlns="http://projectorpsa.com/CommonServices/">2021-12-08T16:07:26.5261911Z</ServerTimestampUtc>
            <a:AccessToken i:nil="true"/>
            <a:ExpiresInSeconds i:nil="true"/>
            <a:MaxLifetimeMinutes i:nil="true"/>
            <a:RedirectUrl>https://secure2.projectorpsa.com</a:RedirectUrl>
            <a:RefreshToken i:nil="true"/>
            <a:RestServiceAuthority i:nil="true"/>
            <a:SoapServiceAuthority i:nil="true"/>
            <a:TimeoutMinutes i:nil="true"/>
            <a:TokenType i:nil="true"/>
            <a:Scope i:nil="true"/>
         </PwsAcquireOauth2TokenResult>
      </PwsAcquireOauth2TokenResponse>
   </s:Body>
</s:Envelope>


PwsAcquireOauth2Token - Common Errors and Warnings


ErrorNumber

ErrorCode

ErrorText

50629OauthUnsupportedGrantTypeUnsupported OAuth2 Grant Type "{GrantType}".
50630OauthInvalidClientInvalid Oauth2 Client.
50631OauthInvalidGrantInvalid Grant for Oauth2 Token: "{InvalidReason}".
50632OauthInvalidRequestInvalid OAuth2 Request in Context "{Context}".  Null or missing parameters "{Missing}".  Improper parameters "{Improper}".
50635OauthUnsupportedTokenTypeUnsupported OAuth2 Token Type "{TokenType}".
  • No labels