search

mozilla / openbadges-backpack

Mozilla Open Badges Backpack
https://backpack.openbadges.org/
Other
862 stars 263 forks source link

Update wiki docs #1023

Closed SueSmith closed 10 years ago

SueSmith commented 10 years ago

Starting on this: Assertion Information for the Uninitiated

threeqube commented 10 years ago

:+1:

SueSmith commented 10 years ago

Had a go at this https://github.com/mozilla/openbadges/wiki/Assertion-Information-for-the-Uninitiated

I've just lifted the structural info from the current spec..

Feedback welcome!

SueSmith commented 10 years ago

Also fixed some links in the assertion spec here https://github.com/mozilla/openbadges-specification/pull/4

SueSmith commented 10 years ago

Making a start on this one next https://github.com/mozilla/openbadges/wiki/Backpack-Connect:-Issuer-Documentation

Trying out the code etc so that I can do it as a step-by-step tutorial.. (and issue myself a few badges)

SueSmith commented 10 years ago

Actually, having had a play around with the code I think I'll do the general issuer API doc next (https://github.com/mozilla/openbadges/blob/development/docs/apis/issuer_api.md), then the backpack connect one. Will let me get to grips with issuing stuff more easily..

One question @cmcavoy @threeqube - although the current issuer API doc is in the /docs, since it's tutorial-style I'm thinking I'll just create a new one on a wiki page for now..?? Maybe redrafting the /docs one to focus exclusively on the detail of installation, methods etc..

threeqube commented 10 years ago

Just had a read of this https://github.com/mozilla/openbadges/wiki/Assertion-Information-for-the-Uninitiated

Looks great but question for @cmcavoy. Here https://github.com/mozilla/openbadges/wiki/Assertion-Information-for-the-Uninitiated#assertion-structure @SueSmith refers to https://github.com/mozilla/openbadges/wiki/Assertion-Specification-Changes Do you think the spec changes is something we should include or just confusing?

threeqube commented 10 years ago

Actually, having had a play around with the code I think I'll do the general issuer API doc next (https://github.com/mozilla/openbadges/blob/development/docs/apis/issuer_api.md), then the backpack connect one. Will let me get to grips with issuing stuff more easily..

This sounds good and makes sense.

One question @cmcavoy @threeqube - although the current issuer API doc is in the /docs, since it's tutorial-style I'm thinking I'll just create a new one on a wiki page for now..?? Maybe redrafting the /docs one to focus exclusively on the detail of installation, methods etc..

This sounds good to me. @cmcavoy?

cmcavoy commented 10 years ago

Yeah, agreed - anything tutorial style should go in wiki until we find a better home for it. /docs should be about more low level documentation.

I'd drop anything that talks about the transition to the new specification, it's been a year...I think we're ok.

SueSmith commented 10 years ago

Cool will get rid of any references to spec changes and update when I've made more progress with the issue stuff.

threeqube commented 10 years ago

:+1: Sounds great. Thanks @SueSmith!

SueSmith commented 10 years ago

Had a go at a tutorial on using the Issuer API: https://github.com/mozilla/openbadges/wiki/Using-the-Issuer-API

Thinking a guide to creating signed assertions might be an idea as well..

Image dump...

issue-error accept-confirmation accept-badge backpack-signin issue-modal

threeqube commented 10 years ago

Thinking a guide to creating signed assertions might be an idea as well..

Agreed. :+1: cc/ @cmcavoy

threeqube commented 10 years ago

As well as tutorial for Displayer API. Thanks @SueSmith!

SueSmith commented 10 years ago

@threeqube yes definitely, can do same as issuer one (tutorial style in wiki for now and refocus /docs page)..

threeqube commented 10 years ago

:+1: Sounds great.

SueSmith commented 10 years ago

First draft of guide to generating signed assertions: https://github.com/mozilla/openbadges/wiki/Creating-Signed-Assertions

:warning: Hope this is correct! (I've only included code I've tried so I know it works but no idea whether I've used a sensible process...)

SueSmith commented 10 years ago

To do:

Also wiki homepage, reorganise sidebar menu etc, until these docs have another home..

SueSmith commented 10 years ago

nb Badge Baking page in specification repo https://github.com/mozilla/openbadges-specification/blob/master/Badge-Baking/latest.md - do tutorial on this in wiki and repurpose /docs version as with issuer/ displayer API..?

threeqube commented 10 years ago

nb Badge Baking page in specification repo https://github.com/mozilla/openbadges-specification/blob/master/Badge-Baking/latest.md - do tutorial on this in wiki and repurpose /docs version as with issuer/ displayer API..?

Yes please.

cmcavoy commented 10 years ago

Creating Signed Assertions https://github.com/mozilla/openbadges/wiki/Creating-Signed-Assertions

Looks good!

SueSmith commented 10 years ago

First draft of new issuer onboarding doc https://github.com/mozilla/openbadges/wiki/Open-Badges-Onboarding:-Issuers

I haven't included everything that was in the wiki.mozilla.org version as I thought it might be better to separate some of the info into different docs, particularly where that info is repeated in various places (e.g. the "why are we doing this"/ background stuff..). Once I have it all represented I'll add plenty of links between the bits.. Hoping it'll be a bit less intimidating to people new to all of this if it's broken down into smaller chunks. We can hopefully also make it easier to navigate between the chunks once it's in some sort of template e.g. on a GitHub pages site.

Hope that sounds ok!

SueSmith commented 10 years ago

For info, pages currently on wiki.mozilla.org:

We talked briefly about this a while back (https://github.com/mozilla/openbadges-badgekit/issues/268) - I guess moving the info to a new location maybe makes it easier to condense it all and just leave the stuff that isn't relevant any more..??

SueSmith commented 10 years ago

Drafting Backpack Connect tutorial - image dump...

backpack-permission backpack-settings bp-grant-permission

SueSmith commented 10 years ago

Draft of new guide to using the Backpack Connect API https://github.com/mozilla/openbadges/wiki/Using-the-Backpack-Connect-API

Thought I'd do all the issuing stuff, then move onto displaying, and so on (for both GitHub and the wiki.mozilla.org docs) - makes me more likely to include everything and also not to repeat too much..

Hope it looks ok!

SueSmith commented 10 years ago

I've stuck a new sidebar on the wiki for now https://github.com/mozilla/openbadges/wiki

It only links to pages that are either new or that we've marked for redrafting, so anything marked for deletion or moving to /docs isn't on there (you can still access it all from the "Pages" link at the top). Should hopefully make it a bit less confusing for new readers.. (Also added a brief paragraph at top of wiki homepage explaining that we're in the process of updating the docs.)

threeqube commented 10 years ago

First draft of new issuer onboarding doc https://github.com/mozilla/openbadges/wiki/Open-Badges-Onboarding:-Issuers

Having a look at this now and a few notes:

Displayers query the badge assertion info (optionally extracting the data from a baked badge)

I haven't included everything that was in the wiki.mozilla.org version as I thought it might be better to separate some of the info into different docs, particularly where that info is repeated in various places (e.g. the "why are we doing this"/ background stuff..).

That sounds good to me.

Once I have it all represented I'll add plenty of links between the bits.. Hoping it'll be a bit less intimidating to people new to all of this if it's broken down into smaller chunks.

Agreed.

We can hopefully also make it easier to navigate between the chunks once it's in some sort of template e.g. on a GitHub pages site. Hope that sounds ok!

Yep this sounds like a fine plan. Sorry if my comment is too long! We can chat through this too.

SueSmith commented 10 years ago

@threeqube Thanks for the feedback! I'm always paranoid about the docs until someone with more of a clue than me reads them over.. (That way I can blame someone else if there are any mistakes :wink:)

So:

On Display section: https://github.com/mozilla/openbadges/wiki/Open-Badges-Onboarding:-Issuers#display should we briefly touch upon the Displayer API?

Added this:

Displayers can use the Displayer API to query for an earner's badges by passing the earner email address, which is converted into a unique internal ID. Earners decide which of their badges are public, determining whether or not a displayer can show them.

For:

nit: on the Display explanation of the Badge Issuing Flow section https://github.com/mozilla/openbadges/wiki/Open-Badges-Onboarding:-Issuers#badge-issuing-flow should we clarify that display can only be made possible with badges made public by the earner?

Added this:

Displayers can only query for badges the earner has chosen to make public

For:

nit: In Creating Assertions section https://github.com/mozilla/openbadges/wiki/Open-Badges-Onboarding:-Issuers#creating-assertions you use "outwith" which is uncommonly used in en-US

Removed, I hardly ever use that word but weirdly decided to for some reason..

I think onus on the displayer to verify and only display if badge is in fact tied to the earner...

Added this:

...displayers are expected to only display badges they have verified as belonging to the earner, using the data included in the assertion

And for:

Are we still allowed to say webapp any longer if we're not gonna do the actual hosting of the service?

I've qualified it a bit with:

If you host both the API and an instance of the Web app...

Will make other adjustments whenever..

threeqube commented 10 years ago

This all looks great @SueSmith! I'd still like @cmcavoy to review and weigh in on the displayer verification piece for good measure. Not sure if it's on the displayer to display only when they have verified that the badge is in fact tied to that earner.

SueSmith commented 10 years ago

Redrafted badge baking wiki page: https://github.com/mozilla/openbadges/wiki/Badge-Baking

I've removed quite a lot since the /docs page gives an overview of how to use the baker API.. Also removed the part about the award parameter, pending confirmation that this isn't recommended (re comments in issue #1025).

SueSmith commented 10 years ago

Redrafting Displayer API docs, just dumping an image.. backpack-convert

SueSmith commented 10 years ago

Still working on Displayer API, dumping another image.. backpack-collection

SueSmith commented 10 years ago

Redrafted Displayer API wiki page https://github.com/mozilla/openbadges/wiki/Using-the-Displayer-API

As with the /doc version, still need to cover verification etc..

SueSmith commented 10 years ago

Draft of guide to revoking issued badges: https://github.com/mozilla/openbadges/wiki/Revoking-Issued-Badges

threeqube commented 10 years ago

Redrafted badge baking wiki page: https://github.com/mozilla/openbadges/wiki/Badge-Baking

Reviewing.

You can bake a badge in various ways, including with the baker API provided within the Mozilla hosted Backpack.

Should we also mention that the Issuer API handles baking for you too?

You may also find this helpful blogpost by Billy Meinke useful.

I've heard from @cmcavoy and @brianloveswords that this blog post is a bit dated now so not sure if we should point folks there.

I've removed quite a lot since the /docs page gives an overview of how to use the baker API..

Fine by me.

Also removed the part about the award parameter, pending confirmation that this isn't recommended (re comments in issue #1025).

Not sure about this. @cmcavoy?

SueSmith commented 10 years ago

Added this:

If you use the Issuer API to push earner badges to the Backpack, it will handle baking the badges for you.

And removed link to blogpost.

Thanks @threeqube

threeqube commented 10 years ago

Great, thanks @SueSmith!

threeqube commented 10 years ago

Redrafted Displayer API wiki page https://github.com/mozilla/openbadges/wiki/Using-the-Displayer-API

Reviewing and looks good.

On this section https://github.com/mozilla/openbadges/wiki/Using-the-Displayer-API#earner-group-badges-response what's in the location field? How are we using that?

As with the /doc version, still need to cover verification etc..

Sounds good.

SueSmith commented 10 years ago

Hmm, I've basically just included what I got back from the Displayer API calls I tried.. I think the location field in the badge object is the URL for the badge class JSON and the location field in the issuer object is the URL for the issuer organization JSON.. So it indicates the links between the three bits of an assertion - does that sound right..?

threeqube commented 10 years ago

Gotcha. Understood. The context for the question was based on discussions around extending the standard to include fields like location data. Hence was wondering how we were using the location field currently when I saw it included here. Thanks!

SueSmith commented 10 years ago

Working on a guide to verifying badges for display and am a bit confused.. this is it (still in progress) https://github.com/mozilla/openbadges/wiki/Verifying-Badges-for-Display

I've been working on the basis that the reader is using the Displayer API to pull badges from the earner's backpack, then verifying them before displaying them. I'm going by the guide to verification on the spec repo: https://github.com/mozilla/openbadges-specification/blob/master/Assertion/latest.md#badge-verification

However, it's written on the basis that you're verifying from either a hosted assertion file or a JSON Web Signature - the backpack displayer API doesn't return those though, it returns something like this for an earner group:

{
    "userId": 12345,
    "groupId": 67890,
    "badges": [
    {
        "lastValidated": "2014-04-28T17:27:22.000Z",
        "hostedUrl": "http://example.org/badge-assertion.json",
        "assertion": {
            "uid": "abcde12345",
            "recipient": "sha256$abcde1345",
            "badge": {
                "name": "Badge Name",
                "description": "Badge description.",
                "image": "https://example.org/badge.png",
                "criteria": "https://example.org/criteria",
                "issuer": {
                    "name": "Issuer Name",
                    "url": "http://issuersite.org",
                    "_location": "http://example.org/issuer-organization.json",
                    "origin": "http://issuersite.org"
                },
                "_location": "http://issuersite.org/badge-class.json"
            },
            "verify": {
                "url": "http://example.org/badge-assertion.json",
                "type": "hosted"
            },
            "issuedOn": 1398705955,
            "_originalRecipient": {
                "identity": "sha256$abcde1345",
                "type": "email",
                "hashed": true
            },
            "issued_on": 1398705955
        },
        "imageUrl": "https://backpack.openbadges.org/images/badge/abcde12345.png"
    },
    ...
    ]
}

For hosted assertions the displayer can just fetch the assertion from the verify.url field and carry out the verification on that - but for signed assertions the backpack doesn't send the signature, so am wondering how the displayer carries out verification?

In particular, the bit on structural validity https://github.com/mozilla/openbadges-specification/blob/master/Assertion/latest.md#structural-validity doesn't apply to the structure you get for each badge from the Displayer API, so is that verification process meant for other cases? Does the displayer not have to carry out all of the verification steps if they're getting the badges from the Backpack?

Sorry if I'm missing something obvious here.. :confused:

threeqube commented 10 years ago

@cmcavoy can you please help with this?

cmcavoy commented 10 years ago

Hey @SueSmith, the assumption is that if the badge is coming from the displayer api, it's a valid badge. We verify it when it comes in. The format of the displayer api predates signed badges. We should add signatures down the line.

SueSmith commented 10 years ago

@cmcavoy thanks, that makes sense..

SueSmith commented 10 years ago

Can I ask for a wee bit of advice @cmcavoy ? Am still working on the verification guide.. I've said that if you're pulling from the Displayer API you can assume the badges are valid. Also said if you're developing in node you can try using openbadges-validator. (Does that sound reasonable?)

Given that, in other circumstances I thought I'd be best giving the examples of verification in a different language, so thought I'd try Python (which I haven't used before today..). I'm trying to show how to verify signed badges using python-jws but am struggling..

This is what I've recommended people do to sign badges: https://github.com/mozilla/openbadges/wiki/Creating-Signed-Assertions#prepare-your-keys

This is the (abbreviated) Python code I'm using with a signature string I generated using that technique:

>>> signature='xxxxx'
>>> payload = signature.split('.')[1]
>>> payloadlen = len(payload)
>>> # payload string may not have correct padding so add it
>>> for x in range(0, 4-(payloadlen%4)):
    payload+='='
>>> # payload successfully decodes to assertion at this point..
>>> pubkey=open('/location/of/my/key/public.pem', 'r').read()
>>> jws.verify({'alg':'RS256'}, decpay, signature.split('.')[2], Crypto.PublicKey.RSA.importKey(pubkey))

...and variations of that...

I just keep getting "could not validate signature". Since I've no idea about JWS or Python I don't know where I'm likely to have gone wrong or whether I should be recommending people do things this way anyway.. Have run out of things to google so any advice would be appreciated! :confused:

SueSmith commented 10 years ago

Just following up on this with more info. Given that I've included an example of using node-jws for issuers to create signed badges, what I'm struggling with is showing an example of using something else i.e. python-jws for displayers to verify the same signature (using the public key corresponding to the private key used for signing).

I can verify in python-jws as long as I've signed in python-jws and the same for node-jws, but am not managing to sign in one and verify in the other.. (should this be possible?) - any tips appreciated!

SueSmith commented 10 years ago

Adding a wee bit to the revocation guide, dumping an image... revoked-badge

SueSmith commented 10 years ago

Draft of new displayer onboarding page https://github.com/mozilla/openbadges/wiki/Open-Badges-Onboarding:-Displayers

cmcavoy commented 10 years ago

Oh wow, @SueSmith you just went beyond my ability to help you easily....heh.

I think verifying the signature in another language is a great idea, but I need to take some time to explore to be able to help you. Adding it to my to-do list. Not sure about ETA.

SueSmith commented 10 years ago

Ha, sorry @cmcavoy - I had found this, which made it sound possible https://github.com/davedoesdev/davedoesdev/blob/master/posts/python-jwt.md but this stuff basically seems like magic tricks to me so anything other than basic usage is a bit beyond me.. Can totally keep the guidance general for now anyway.