I am using the DocuSign REST API to send documents and we are trying to take advantage of the webhook capabilities.
Our problem is that we have basic auth set up on our webhook listener which it doesn't appear is supported in the REST API. I am enquiring whether or not this is an accurate understanding. I know it is possible on the Connect product, which the basic auth can be set up via the portal, however I am looking specifically for API REST calls.
How can I secure the EventNotification event?
Many thanks,
Mitch.
As of now, according to docusign offical post:
Individual Envelope Connect configurations created with the eventNotifications API option do not support Basic Authentication at this time.
A WORKAROUND SOLUTION:
Docusign has an official blog post to answer this question. Securing Your Connect Webhook Listener
For us, we use the Use a Pre-shared Secret method to secure our webhook. We are using the python sdk. During the process we create the EventNotification, we add a secret parameter to the webhook listener url. When the docusign post the request to your listener server, it will include the secret. You could check the parameter to make sure the request is valid.
event_notification = EventNotification()
event_notification.url ='your webhook_url' + '?secret=' + 'your_secret')
The text below is quoted from the blog post.
This defense acts both as access control and authentication. The
listener URL you provide to DocuSign can include one or more query
parameters. DocuSign will include them during its POST request to your
listener.
For access control, your listener will first check that the request
includes the expected query parameter and reject all requests that
don’t. For authentication, your listener will additionally check the
value of the query parameter. Remember that you can encode any values
for the name and value of the query parameter. For this example, we’re
using “pw” as the name of the query parameter.
To use a pre-shared secret, just set the URL accordingly in the
Connect configuration. For example,
https://listener_url.example.com/listener?pw=secret
Remember that the complete URL, including its query parameters, is
encrypted before it is sent across the internet. The URL and its query
parameters are visible in various logs and configuration screens,
including the Connect webhook configuration page.
Related
I am trying to change account email in Keycloak, but did not find any useful information in the Keycloak official documentation.
I tried work with this endpoint
PUT /admin/realms/{realm}/users/{id}/execute-actions-email
but it only accepts an array of actions and sends to a user an email to perform specified actions.
But I want to update it directly performing my request. Is this possible?
I think you are looking for below API.
PUT /admin/realms/{realm}/users/{id}
with a JSON payload as below.
{
"email":"new#email.com"
}
The Problem
MS Azure provides an extensive REST API. However, there is a significant amount of complexity when trying to get that API to work. From outdated and incomplete documentation to simple examples not working, performing what should be an easy task is instead nightmarish.
The Task
What are the exact, precise, detailed steps necessary to list the available VMs for someone who has logged in using Oauth2? For instance, this can be done using the azure-cli.
azure vm list
What are the steps to accomplish the same thing using REST and Oauth2?
The Requirements
The answer must not use Visual Studio, PowerShell, C#, an SDK, or any other such tool to accomplish this task. Only the portal is allowed for setup, and only Oauth2 is allowed for authorization, and only the REST API is allowed for actual information retrieval.
The answer must not simply link to external sources, although external references are encouraged for completeness.
The answer may assume the user has an Azure account. It must include information about creating the Oauth2 client, credentials, and any step necessary to get the appropriate token.
The answer must be detailed.
The answer must provide examples. Images, too are strongly encouraged.
The answer should include information about possible errors, their meanings, and what too look for to fix them.
First, we can find this rest API in azure resource portal. It is the same with Azure CLI command azure vm list.
I have tested it on my local with http request. here is my tested screenshot:
Request URL: https://management.azure.com/subscriptions/<subscription ID>/providers/Microsoft.Compute/virtualMachines?api-version=2016-03-30
Header:Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI.....
So It is very import if we get the access token. The following demonstrate us how to get the access token.
Get Token(POST):
Request URL: https://login.microsoftonline.com/<tenant id>/oauth2/token
Body: grant_type=client_credentials&client_id=<client id>&resource=https%3A%2F%2Fmanagement.core.windows.net%2F&client_secret=<client secret>
Here is my screenshot in fildder:
We need to get client id and client secret in azure ad application. For how to regist an application in Azure AD. Please have a look at this article: https://learn.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal.
Please note:
1) we need to add "Windows Azure Service Management API" in portal "Required permissions" like the following screenshot:
2) We need assign "Contributor" for this service principal. click subscription-> Access Control-> click Add -> click "Select a Role" -> click Contributor->click Add User-> Find the application you created above-> click OK.
Overview
Making requests against the Azure Rest API is a bit more complicated than perhaps you would think at first glance. In particular, there are a number of esoteric and not-so-helpful error messages you may run into while getting the nobs tweaked just right.
Introduction and Terms
Setting up The Application
Getting the access_token
Making the API request
Common errors thus far
Introduction and Terms
One of the pieces of this process that can make it so confusing and difficult is the terminology. Until you understand that, knowing how to deal with errors is very difficult. We'll go over some of the more common ones here.
Subscription - This is basically what you'd expect. It refers to the Microsoft Azure Services subscription. It basically acts as the top-level umbrella for the organization.
Tenant - This is like a sub-organization, maybe a department or group. There can be multiple tenants under a single subscription.
User - As expected, a user is a single individual. Users are scoped to tenants.
Application - The Application is the software program trying to use the API. It must be registered and configured to do so.
Service Principal - This is essentially The Application. It is the entity making API Service requests.
Setting Up the Application
Although you might not guess it, this is probably the most complicated part of the process. Let's start by creating The Application in the portal.
Create The Application
Follow this click path: Azure Active Directory -> App Registrations -> New
There should be a form for application creation, with the following fields:
Name
This is simple the name of The Application. When authenticating, it will be shown to users. For the purposes of this "tutorial", we'll call it API Tutorial. This can be edited after creation.
Application Type
The type of The Application. For our purposes, we should choose "Web app/API". This cannot be edited after creation.
Sign-on URL
The is the redirect that will be used if we go the "authorization_code" route for sign on. This can be useful as the response will include an "id_token". We'll get into that a bit later. For now, let's make this http://123AzureApiTutorial.com/code. This can be edited after creation.
Once the Application has been created, you should see a property, Application ID. This is the client_id used in the OAuth2 flow. Take a note of its value.
Create the Client Secret
The OAuth2 flow requires a client secret value for authentication.
To generate it, follow this click path: Azure Active Directory -> App Registrations -> API Tutorial -> All Settings -> Keys
Enter the key description: API Tutorial Key, and the Duration: In 1 year.
Click Save. This will generate the Key Value. You must copy the value here and save it somewhere. You will not have another opportunity to do so.
This value is the client_secret in the OAuth2 flow.
Add the correct permissions
To get to the permissions, follow this click path: Azure Active Directory -> App Registrations -> API Tutorial -> All Settings -> Required Permissions -> Add
Here you will see the list of possible APIs. The one we care about for Azure is Windows Azure Service Management API. There is currently only one permission: Access Azure Service Management as organization users (preview). Select it, click Select, and then Done.
Getting the access_token
The access_token is what allows us to make requests against the API. There are two primary ways to do this. I suggest reading about both before trying to implement them.
Authorization Code
The authorization code is a two-step process. First we obtain the authorization code, and then we use that to get the access_token. A benefit of this route is that we get back an id_token as well, with a variety of useful claims like the user's name, email address, etc.
The request format is as follows: (GET) https://login.microsoftonline.com/<tenant-id>/oauth2/authorize?client_id=<client-id>&scope=api&redirect_uri=<redirect-uri>&response_type=code&prompt=consent. Let's go over the parameters here really quick.
Tenant ID
This can be obtained be using the click path Azure Active Directory -> Properties and copy the Directory ID. This is, in fact the Tenant ID value. It just has a different name to help with the overall confusion.
Client ID
This is the Application ID we retrieved previously.
Scope
This is the scope of the code. We just want to use the API.
Redirect URI
This is the sign-on URL you specified when creating API Tutorial. After the user logs in, they will be redirected to this URL with a "code" parameter in the query string.
Response Type
This is what we want the response to be. We want an authorization code, so we just use the value code.
Prompt
This specifies whether or not to prompt the user to consent to the permissions. If we did not have this, and changed permissions, the request would just unexpectedly fail. Very frustrating. But it can be removed once permission has been granted as long as you don't change the permissions. If the application is accessing an API that requires admin permission, this value should be admin_consent.
Alright, so once we shoot off this request we will be redirected to the login page. We login, accept the permissions, and then we should be redirected to here: http://123AzureApiTutorial.com/code?code=SOME_REALLY_LONG_STRING_OF_CHARACTERS. That string of characters is the code.
Getting the Access Token
Next, we take the code and use it to get the access_token. To do so, we need to make another request.
(POST) https://login.microsoftonline.com/<tenant-id>/oauth2/token
In addition to the url, we need to add parameters. These should be consistent with the content type application/x-www-form-urlencoded. This means they are submitted as form parameters. They are as follows:
client_id
This is again the client id (Application ID) we already have.
client_secret
This is the Application Key we generated earlier. I hope you saved it! If not, go back to that step and generate another one.
code
This is the value of the code we just received: SOME_REALLY_LONG_STRING_OF_CHARACTERS.
`grant_type
Because we're going the authorization code route, this value should be authorization_code
redirect_uri
This is the redirect uri we specified for the API Tutorial. The value from our example should be http://123AzureApiTutorial.com/code.
resource
This is very important. It is the resource API we want to access. For the Azure API, this value is https://management.azure.com.
Our response will be a json object with a variety of fields. Of these, the one we care about is access_token. Yay!
Client Credentials
This methodology skips getting the code (and thus needing the redirect_uri) at the expense of not getting an id_token.
The request is the same as in the Getting the Access Token section, with a few small differences.
We do not need to specify redirect_uri.
The value of grant_type should change to client_credentials.
Alright, we have an access_token! Now we're cooking!
Making the API request
With all the prep work thus far, this is the easiest part of the process.
The API URL we are requesting against is:
https://management.azure.com/subscriptions/<subscription-id>/providers/Microsoft.Compute/virtualMachines?api-version=2016-03-30
Add the following header to the request:
Authorization: Bearer <access-token>. Yes, the access_token value must be prefaced with the word "Bearer" in the header value.
"But wait!" You exclaim. "How do I get the subscription id?"
Excellent question! To find it through the portal, click Subscriptions -> -> Overview and copy the Subscription Id value.
Use that value, and run the request. You should see all the vms listed!
Common errors thus far
InvalidAuthenticationToken
When making the API request, you get an error response that says something like this: InvalidAuthenticationToken: The access token is invalid. This means you haven't added the API permissions to the API Tutorial. Go back to the Add the correct permissions step and double-check you have the right permissions. Also, when requesting the token make sure you use the prompt=consent, otherwise the you will not be prompted with the new permissions and the token will fail.
InvalidAuthenticationTokenTenant
Make sure that the tenant-id used when requesting the token belongs to the subscriber used when making the API call.
I'm trying to Enable/Disable a logic app on Azure using the management APIs. I always get a 403 saying the client: with object id does not have authorization to perform 'Microsoft.Logic/workflows/disable/action' ...
I do use the authentication token in my request and so far have been able to use the API to list all workflows, get trigger histories and in/out messages using the same method.
Any suggestion?
I've seen this issue a lot before if you are calling the http:// instead of https:// - we are looking into automatically redirecting, but for now you will need to make sure you are calling the https:// endpoint with the correct method (in this case a PUT)
EDIT: We discovered the issue was the account being used to perform the enable/disable didn't have contribute permissions.
Background
I have a RESTful API accessed through the domain http://restapi.com
I have a client app using http://restapi.com. The client app has the domain http://myapp.com
The way I have my HATEOAS setup is that the API presents URIs without a domain. So instead of http://restapi.com/some/resource, it contains links to resources like so /some/resource. Example API json resource below:
{"_links":{"self":{"href":"/some/resource"}}}
The benefit this has is that the API doesn't need to know about the client app, and the client app has to do very little to get the correct resource from the API and doesn't have to reformat all the URIs in the resource. For example, in the client app, the following URI would be used by the browser http://myapp.com/some/resource. When the app gets the request, it then needs to call the API to get the resource and simply swaps the domain i.e. http://restapi.com/some/resource.
This has been successful so for, and allows a lot of flexibility to have different clients use the API with the only knowledge required being the initial end point (domain) of the API. It also completely decouples the API from the client apps.
The problem I have run into is that I have started using some external services (specifically PayPal adaptive payments) where I need to provide a redirect URL for cancelled payments and successful payments. For example, the browser navigates to http://myapp.com/payment. The resource returned by http://restapi.com/payment presents a link to PayPal. Without going into too much detail, the API has to ask PayPal for a payment ID, which can then be used to create a link to a PayPal payment e.g. http://paypal.com?PayId-123456. Part of the creation process requires that URLs are provided to redirect on payment cancellation or success. Again, don't want to go into details, but when requesting a PayId from PayPal, the redirect URLs are sent as variables to PayPal, and I guess PayPal stores them against the specific PayId created.
The browser navigates to the link returned in the resource - http://paypal.com?PayId-12345. Payment is made and PayPal then uses the redirect URLs as needed to redirect back to my app e.g. on successful completion of payment, PayPal should redirect to http://myapp.com/paymentcomplete. Note: I realise that this is not a restfully named URI, but it simplifies building up the description of my problem
Problem
The problem I have may now be obvious. I need to redirect back to http://myapp.com/paymentcomplete, BUT its the API that provides the redirect URL to PayPal. It has no knowledge of the client application. Since PayPal is an external service, the full URL must be provided. The best the API can do is send http://restapi.com/paymentcomplete as the redirect URL, but if PayPal redirects to this, the resulting response will be a JSON string (the output format of my API) not the nicely formatted page of the client app.
My question is, what is a good way to correctly provide the redirect URL to PayPal?
One thought I had was to make the client application handle creating the PayPal PayId, but I don't like this option as I would like to keep the creation of the PayPal payment ID on the API side. It would also require every client app to provide its own implementation, something I also don't want.
The other option I though of was to ask the client to provide its domain in the request. Currently the request the client makes to get the resource with the link to PayPal is GET http://restapi.com/payment, but I could use POST http://restapi.com/payment with the client providing its domain as a param. The API can then use this to construct the correct redirect URL. I don't really like this idea either as its seems a bit hackish and also requires the app to know that is must fill in this field i.e. a human user wouldn't fill the domain input in.
Additional solutions, or thoughts greatly welcomed.
As you had already mentioned, PayPal is an external api that requires this additional parameter and you do not have control over it. Looks like the client is the only party that can provide the Redirect URI Information.
Couple of ideas come to mind.
The client could send the redirect uri to restapi via header and thus
keeping your rest urls intact. This is a grey area and not a violation of restful api
in my opinion. (Then again, its just my opinion).
The restapi could return the response with a placeholder for the
client to fill in before rendering. This way the API need not know
about the redirect uri and the responsibility is left to the client
which has this information.
It would be nicer if you could implement option 2 with executing couple of lines on Javascript code on the browser to fill-in the placeholder. Which is easy. Ultimately, only 2 end points of this transaction would be aware of the redirect uri - browser & paypal.
This alleviates most of your concerns. The job of handling PayPal id will continue to remain with your API.
You should be able to use the Referer header to determine the client's full URI. It might be populated automatically for you. If not, you can add it yourself. The URI class has methods to pull out the client's host for you. When the API builds the PayPal URI to return to the client, it can include the client's host.
Note that referer is not always included and sometimes gets stripped by intermediaries, as detailed on the wiki page. Since you control both the client and the server in this case, you should be able to tell everybody to play nicely.
I would keep the GET http://restapi.com/payment and pass in a query param with the client domain
GET http://restapi.com/payment?domain=http://myapp.com (of course, the "http://myapp.com" needs to be encoded)
I have seen many different posts regarding different solutions for authenticating a RESTful API and I have some questions, given this current scenario.
I've built a REST API that will allow clients of my software service (we are a B2B company) to access resources programmatically. Now that I've got the API working properly, I'd like to secure it in the most standardized way possible. I need to allow access to certain resources based on the caller of the API. That is to say, not all users of the API can access all resources.
I have URLS available in the following formats:
https://mydomain/api/students
https://mydomain/api/students/s123
https://mydomain/api/students/s123/classes
https://mydomain/api/students/s123/classes/c456
So far I've come up with these possible solutions:
Provide a unique key to each client that they can use to ultimately generate an encrypted token that will be passed as a GET parameter at the end of each REST call to (re)-authenticate every single request. Is this approach too expensive
https://mydomain.com/api/students/s123?token=abc123
Provide a value in the HTTP Authorization Header as seen here. Is this almost the same as #1? (Except I can't paste a URL into the browser) Do people use these headers anymore?
Use OAuth 2 (which I'm still a bit unclear on). Does OAuth 2 actually authenticate the client as a logged in user? And doesn't that go against the spirit of a REST API being stateless? I was hoping OAuth was the proper solution for me (since it's a public standard), but after reading up on it a little bit, I'm not so sure. Is it overkill and/or improper for REST API calls?
My goal is to provide an API that will not have to be changed for each client that wants to consume the API, but rather that I can provide a standard documentation made available to all of our clients.
I'll be happy to post additional details if I've been unclear.
There are 2 type of clients you probably want to prepare your API:
trusted clients - Which are written by you. They can have the username and password of the actual user, and they can send that data to your server with every request, possibly in a HTTP auth header. All you need is an encrypted connection by them.
3rd party clients - Which are written by some random developer. You can register them in your service and add a unique API key to each of them. After that if an user wants to use their services, you have to show her a prompt in which she can allow access to the 3rd party client. After that the 3rd party client will be assigned to the user's account with the given permissions and it will get an user specific access token. So when the client sends its API key and the user specific token along with the request, then it sends the requests in the name of the user.
OAuth can help you to control the second situation.
Your URLs do not have a meaning to the clients. By REST you have to decouple the clients from the URL structure by sending links annotated with semantics (e.g. link relations). So your documentation does not have to contain anything about the URL structure (maybe it can be useful for server side debug, but nothing more). You have to talk about different types of links. By generating these links on server side, you can check the permissions of the actual user (or 3rd party client) and skip the links which she does not have permission to follow.